Core Resource Objects¶
On this page:¶
This page describes the core JSON objects used by the PB Shipping APIs:
Address
|
The origin or destination address for a shipment. |
Categories | Categories associated with a CBDS shipment or quote. |
Country | A country and its two-character ISO country code. |
Customs Info | Customs-clearance information for a commercial invoice. |
Customs Items | Customs-clearance information about each commodity in a shipment or shopping cart. |
Documents | The shipment documents, including the label. |
Domestic Shipment Details | Information about the domestic leg of a CBDS shipment. |
Hazmat Details | PB Standard Only. Hazardous goods information if shipping with PB Standard. |
Manifest | The end-of-day form that lists all parcels or shipments. |
Merchant | The shipper. Each merchant is uniquely identified by the value of the postalReportingNumber field. |
Parcel | The physical characteristics of a parcel. |
Pickup | The details of a scheduled package pickup. |
Rates | The shipment’s service, special services, parcel type, and dimensions. In a response, this object also includes the shipment’s charges. |
Shipment | The high-level object that includes all the information about a shipment. |
Special Services | The special services applied to the shipment. |
Transaction | Detailed information associated with a transaction. |
Address Object¶
The address object contains the origin or destination address for a parcel.
Name | Data Type | Description |
---|---|---|
addressLines | Array[String] | Conditional. Street address or P.O. Box. Include apartment number if applicable. You can specify up to 3 address lines. See the API request’s documentation page for whether this field is required. USPS: For USPS domestic destinations, 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, postal ZIP code, per USPS label guidelines. |
cityTown | String | Conditional. The city or town. See the API request’s documentation page for whether this field is required. |
stateProvince | String | Conditional. The state or province. For a US or Canadian address, use the 2-letter state or province code. See the API request’s documentation page for whether this field is required. |
postalCode | String | Conditional. 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:
If you use a different format, such as See the API request’s documentation page for whether this field is required. |
countryCode | String | Conditional. Two-character country code from the ISO country list. See the API request’s documentation page for whether this field is required. |
company | String | Conditional. The name of the company. See the API request’s documentation page for whether this field is required. |
name | String | Conditional. The first and last name. See the API request’s documentation page for whether this field is required. |
phone | String | Conditional. The phone number. Enter the digits with or without spaces or hyphens. When used for Pickups, the maximum is 10 digits. See the API request’s documentation page for whether this field is required. |
String | Conditional. The email address. See the API request’s documentation page for whether this field is required. | |
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:
|
Categories Object¶
Name | Data Type | Description |
---|---|---|
categoryCode | String | Required. The item’s category identifier based on the product categories agreed on with Pitney Bowes. The maximum length is 50 characters. |
parentCategoryCode | String | Parent category of the item’s category identifier, based on the merchant product categories agreed on with Pitney Bowes. Maximum 50 characters. |
descriptions | Array[Object] | The description of the category. You can include multiple objects for descriptions in multiple languages. |
locale | String | The language used for the category description. For example, en_US . The
maximum length is 10 characters. This field is required by the descriptions array. |
name | String | The category description. The maximum length is 255 characters. This field
is required by the descriptions array. |
parentsNames | Array[String(255)] | The tree of parent names to reach this category. parentNames[0] must be
the top-level name, and parentNames[Max Length-1] must be the name of the
parent category containing this category. Maximum 255 characters. |
categoryNamePath | String | Hierarchical path to the category represented by the category name of each
level, concatenated with a pipe ( CONSUMABLES AND GROCERY|BABY|BABY CARE|BABY CONSUMABLES|BABY FOOD
|
categoryCodePath | String | Hierarchical path to the category represented by the category ID of each level, concatenated with a colon delimiter. For example: 9785:8266:9798:9799:10203
|
categorySiteId | String | The category site ID if the eBay category is referred. |
Country Object¶
Name | Data Type | Description |
---|---|---|
countryCode | String | The two-character ISO country code. |
countryName | String | Country name. |
Customs Info Object¶
Name | Data Type | Description |
---|---|---|
certificateNumber | String | The certificate number associated with the commodity. |
comments | String | Free form comments regarding the exported shipment entered by the shipper. |
currencyCode | String | Required. The type of currency used for the monetary values in this API request. Use
three uppercase letters, per ISO 4217. For example, use USD for US
Dollars, CAD for Canadian Dollars, and EUR for Euros. For all
currency codes, see https://www.iso.org/iso-4217-currency-codes.html. |
businessType | String | CBDS Quotes API Only. Enter the type of transaction. Valid values are:
|
customsDeclaredValue | BigDecimal | Conditional. Enter the value to declare in customs for the shipment.
Enter the value in the currency specified in the This field is required for FedEx. |
EELPFC |
String | Conditional. A number provided by the Automated Export System (AES). This field is required if the item is valued at more than $2,500 USD per Schedule B export codes. |
firstMileInsuredAmount | BigDecimal | CBDS Only. For merchants who use the CBDS drop-off solution, enter the insurance fee associated with bringing the parcel to the Pitney Bowes facility, if applicable. The value is used in the duty-and-tax calculation for countries that include the fee in the calculation. |
firstMileShippingAmount | BigDecimal | CBDS Only. For merchants who use the CBDS drop-off solution, enter the shipping cost associated with bringing the parcel to the Pitney Bowes facility. The value is used in the duty-and-tax calculation for countries that include the cost in the calculation. |
freightCharge | BigDecimal | FedEx Only. For merchants who ship with FedEx, this field prints a freight charge on the FedEx Commercial Invoice. This field is optional. Note: If this field appears in the response for a carrier other than FedEx, it will have a value of 0.0 and can be ignored. |
fromCustomsReference | String | Free form reference information provided by the requestor of the shipment. Depending on the carrier this information may or may not be rendered on the customs documents. |
handlingCosts | BigDecimal | FedEx Only. For merchants who ship with FedEx, this field prints a handling charge on the FedEx Commercial Invoice. This field is optional. Note: If this field appears in the response for a carrier other than FedEx, it will have a value of 0.0 and can be ignored. |
importerCustomsReference | String | Conditional. A reference number used by the importer. For example, a PO number or insured number. This field is required for shipments to Brazil. Use this field to
provide the Importer’s Tax Identification (ID) Number. Brazil requires the
Tax ID for all imports. Items missing the Tax ID are subject to return. If
using the First-Class Package International Service ( |
insuredAmount | BigDecimal | CBDS & FedEx Only. Conditional. Enter the insurance fee, if applicable. This field is used as follows:
Note: If this field appears in the response for a carrier other than the
above, it will have a value of |
insuredNumber | String | If the sender wishes to insure the contents, they complete an insurance receipt and affix the insured numbered label to the package. The insured number label is what this field represents. |
invoiceNumber | String | The commercial invoice number assigned by the exporter. |
licenseNumber | String | The export license number associated with the commodity. |
otherCharge | BigDecimal | FedEx Only. For merchants who ship with FedEx, this field prints any
additional charges on the Commercial Invoice, other than those entered in
the Note: If this field appears in the response for a carrier other than FedEx, it will have a value of 0.0 and can be ignored. |
packingCosts | BigDecimal | FedEx Only. For merchants who ship with FedEx, this field prints a packing charge on the FedEx Commercial Invoice. This field is optional. Note: If this field appears in the response for a carrier other than FedEx, it will have a value of 0.0 and can be ignored. |
portOfClearance | String | CBDS Quotes API Only. Conditional. If the port of clearance for a
shipment is different from the country of destination, enter the
two-character ISO country code for the port of clearance. For example, enter
If the port of clearance and destination country are the same, leave this field blank. This field is required if the port of clearance is different from the country of destination and if the merchant uses the CBDS digital-only solution (i.e., does not ship via CBDS). |
reasonForExport | String | The reason the commodity is being exported. Valid values are:
Note: For USPS First-Class Mail International ( |
reasonForExportExplanation | String | Conditional. The reason the commodity is being exported. This field is required for USPS if the |
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 API Only. Conditional. Enter the end-to-end shipping
cost. Enter the cost in the currency specified in the currencyCode
field. The value is used in the duty-and-tax calculation for countries that
include the cost in the calculation. This field is required if the merchant
uses the CBDS digital-only solution (i.e., does not ship via CBDS). |
shippingDocumentType | String | UPS Only. |
termsOfSale | String | UPS Only. |
Customs Items Object¶
Column 1 lists the fields alphabetically. Column 3 identifies the carriers that use the field.
Name
|
Data Type
|
Description
|
---|---|---|
brand | String | CBDS Only. The manufacturer’s brand name for the item. The maximum length is 255 characters. |
categories | Array[Categories Object] | CBDS Only. Conditional. Associated categories. The merchant’s category tree must have been provided to Pitney Bowes in advance. Do not use this array if the merchant did not provide a category tree. This field is required by the HS Code API. |
condition | String | CBDS Only. Condition of the commodity. If the merchant is using an eBay-specific category tree, enter the eBay item’s conditionId. Otherwise use one of the following values:
|
description | String | Required. A detailed description of the commodity. For CBDS, make the description as detailed as possible to facilitate assignment of the correct HS Code. |
eccn | String | CBDS Only. The Export Control Classification Number (ECCN) for the commodity. The maximum length is 10 characters. |
hazmats | Array[String] | CBDS Only. For a HAZMAT-flagged item, enter one or more of the HAZMAT classifications listed here. |
hSTariffCode | String | Conditional. The destination country’s tariff-classification number for the commodity. Most countries use the six-digit Harmonized System (HS) as the basis for their tariff classifications and add additional digits for more detail. The maximum length is 14 characters. If you are issuing the HS Code API, you can use this field to help with the
HS Code prediction by entering the commodity’s HS Code from another country,
such as from the origin country. Enter the country that the code comes from
in the This field is required by the CBDS Quotes API. |
hSTariffCodeCountry | String | CBDS Only. Conditional. The two-character ISO Country Code for the country supplying the HS Code. This is usually the destination country. This field is required if the |
identifiers | Array[Object] | CBDS Only. Additional identifiers for the item. Each object in the array defines a type of identifier and its value. |
source | String | CBDS Only. The type of identifier, such as MPN , SKU , UPC , ISBN , or
ISSN . Enter the identifier as a String of up to 10 characters. This
field is required by the identifiers array. |
number | String | CBDS Only. The value of the identifier. Enter a String of up to 50 characters. This
field is required by the identifiers array. |
imageURL | Array[String] | CBDS Only. Enter one or more URLs that link to an image of the commodity. Enter the URLs as Strings, separated by commas. |
itemDimension | Object | CBDS Only. The dimensions for a single item. |
length | BigDecimal | CBDS Only. The longest dimension. This field is required by the itemDimension object. |
height | BigDecimal | CBDS Only. The second longest dimension. This field is required by the itemDimension object. |
width | BigDecimal | CBDS Only. The shortest dimension. This field is required by the itemDimension object. |
unitOfMeasurement | String | CBDS Only. The unit of measurement. This field is required by the
|
itemId | String | CBDS Only. Required. The merchant’s unique identifier for the commodity, such as the SKU. The maximum length is 50 characters. |
manufacturer | String | CBDS Only. The manufacturer of the item. The maximum length is 255 characters. |
netCostMethod | String | UPS Only. |
originCountryCode | String | Conditional. The two-character ISO country code of the shipment’s origin country. Use ISO 3166-1 alpha-2 standard values. This field is required by FedEx and UPS. |
originStateProvince | String | UPS Only. |
preferenceCriterion | String | UPS Only. |
pricing | Object | CBDS Only. The pricing information for the commodity. If the information is not in the shopping cart, then this information is used. |
price | BigDecimal | CBDS Only. List price of the item. |
producerAddress | Address Object | UPS Only. |
producerDetermination | String | UPS Only. |
producerId | String | UPS Only. |
quantity | Integer | Required, except for the HS Code API. Enter the total number of items of this type of commodity. For USPS, the number of items cannot exceed 9999. USPS limits the number of items of one commodity to 9999. Note: This field is optional for the HS Code API. |
quantityUOM | String | FedEx, UPS Only. Required. The 1-to-3 character code for the unit of
measurement, such as BAG , CTN , or EA . |
unitPrice | BigDecimal | Required. The price of one item of this type of commodity. |
unitWeight | Object | Required for all international shipments, except CBDS shipments. The weight and unit of measure of one item of the commodity. Note: For CBDS, this field is optional. |
weight | Number | The weight of the item. This field is required by the unitWeight object. |
unitOfMeasurement | String | The unit of measurement. This field is required by the |
url | String | CBDS Only. Recommended. The commodity’s URL on the merchant’s site. Ensure the URL works. Providing an accurate URL helps Pitney Bowes assign the correct HS Code. The maximum length for this field is 1000 characters. |
Documents Object¶
Name | Data Type | Description |
---|---|---|
type | String | The type of document. Valid values are:
|
size | String | Conditional. The recommended size of the label. The actual size of a label depends on the carrier. This field is required if the type field is set to SHIPPING_LABEL. For the valid values for your API call, see the Labels section of the carrier’s reference page. The field’s possible values are listed below, but see the carrier’s reference page for valid values:
|
contentType | String | Conditional. Determines whether the API returns the document as a URL or a Base64-encoded string. The field is required for USPS, PB Standard, and PB Presort. For the valid values for your API operation, see the Labels section of the carrier’s reference page. The field’s possible values are:
|
fileFormat | String | Conditional. The file format for the document. This field is required if the type field is set to SHIPPING_LABEL or QR_CODE. For the valid values for your API operation, see the Labels section of the carrier’s reference page. The field’s possible values are:
|
resolution | String | USPS & PB Standard 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 USPS 4X8 labels, USPS COD labels, and USPS PMOD labels. This field can take the following values, depending on the carrier, label settings, and other conditions:
|
printDialogOption | String | Conditional. If Valid values are:
|
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. For more information, see How do I print a Doc Tab label? |
name | String | The field to be printed. This can be an existing field returned by the
Create Shipment API or a custom field that you define. Each object
in the docTab array must have a name value. |
displayName | String | If For example, if you set the following:
The label will display:
where <parcelTrackingNumber> is the value of the parcelTrackingNumber field. If you don’t define a |
value | String | To display a field and value that are not returned by the Create Shipment API,
enter the new name in the
|
contents | String | Response Only. When Note: The document is available for 24 hours after it is created. |
pages | Array[Object] | Response Only, Shipping Labels Only. When contentType is
BASE64 , this array contains the pages in the shipping label. The array
contains multiple objects if the label has multiple 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 pass custom values that perform additional functionalities, such as printing merchant information on labels or applying merchant business rules. Merchants must set up the customizations in advance with their PB implementation teams. If the merchant is configured to print a custom barcode (third barcode) on a PB Standard Returns label, use this object. |
labelDetails | Array[Object] | The array contains name-value pairs with custom values used to print additional label data or apply additional business rules, depending on the merchant’s setup with the Pitney Bowes implementation team. If the merchant is configured to print a custom barcode (third barcode) on the label, use this array. |
name | String | The name of the custom function. |
value | String | The value for the custom function. |
Domestic Shipment Details Object¶
Name | Data Type | Description |
---|---|---|
shipperTrackingNumber | String | Required. The tracking number for the domestic leg of the shipment. |
carrier | String | The carrier for the domestic leg of the shipment. If you are using one of the following carriers, enter them as follows:
|
dcAddress | Address Object | The origin address for the domestic leg of the shipment. The parcel is shipped from this address to the CBDS Consolidation Center. |
Hazmat Details Object¶
PB Standard Only. This object provides details for a PB Standard shipment that includes hazardous materials or dangerous goods.
Name | Data Type | Description |
---|---|---|
batteryDetails | Object | Details about the batteries or cells contained within this package. |
batteryMaterial | String | The material composition of the batteries or cells. |
batteryPackaging | String | The packing arrangement of the batteries or cells with respect to other items within the package. |
regulatory | String | A regulation-specific classification for the batteries or cells. |
commodityType | String | Description of the material being shipped. For example: Explosives ,
Gases , FlammableCombustibleLiquids , FlammableSolids , etc. |
containerCount | Integer | The number of occurrences of this container with an identical dangerous goods configuration. |
containerDetails | Array[Object] | Indicates one or more containers used to pack dangerous goods commodities. |
commodityInfo | Array[Object] | Information about the material inside the containers. |
hazardClass | String | Class of the specified commodity. For example: Explosives , Gases ,
FlammableCombustibleLiquids , FlammableSolids , etc. |
quantity | Integer | The amount of the commodity. |
quantityUOM | String | The unit of measure. |
emergencyContactNumber | String | The telephone number to contact in the event of an emergency. |
hazmatDocumentType | String | The type of document required for hazmat shipping. |
identicalContainers | Boolean | Set to true if the containers being shipped are identical. |
offeror | String | The offeror’s name or contract number, per DOT regulations. |
packagingOption | String | The type of packaging to be used for shipping. |
signatory | Object | The signatory for the shipment. |
name | String | The signatory’s name. |
title | String | The signatory’s title. |
place | String | The signatory’s place. |
Manifest Object¶
Name | Data Type | Description |
---|---|---|
carrier | String | Required. The carrier to which the manifest applies. For some operations, this field is not present in the response. Valid values:
|
submissionDate | String | Required. The date the shipments are to be tendered to the carrier,
entered as YYYY-MM-DD . |
fromAddress | Address Object | Conditional. The shipment origin address. Required for: |
inductionPostalCode | String | Conditional. Postal code where the shipments are tendered to the carrier. This field does not apply to PB Standard manifests. |
parcelTrackingNumbers | Array[String] | Identifies shipments by their tracking numbers. List one or more tracking numbers, separated by commas. Enter each tracking number as a separate String. If the |
parameters | Array[Object] | Conditional. Each object in the array defines a different manifest parameter. This field is used only in the request and is not returned in the response. Required for PB Standard manifests (closeouts). |
name | String | The name of the manifest parameter. |
value | String | The value of the manifest parameter. |
manifestId | String | RESPONSE ONLY. The unique manifest ID. This field is not returned for APAC Services. This field is not returned for APAC Services. |
manifestTrackingNumber | String | RESPONSE ONLY, USPS Only. The manifest tracking number. |
documents | Array[Documents Object] | RESPONSE ONLY. The manifest. This field is not returned for a PB Standard manifest. |
Manifest Parameters¶
In the Manifest Object, the parameters
array can take the following
options:
Parameter | Description |
---|---|
SHIPPER_ID | Adds shipments to a manifest by specifying the Shipper ID that was used to create the shipments. For the parameter value, specify the Shipper ID. A merchant’s Shipper ID is found in the Merchant Object’s |
MANIFEST_TYPE | Specifies the type of manifest. Required if creating a PMOD manifest (PS Form 3152). Valid values are:
|
CLIENT_ID | PB Standard Only. The unique ID assigned to the
merchant to use with PB Standard. If testing in the Sandbox environment, set
this to Required for PB Standard manifest requests. |
CARRIER_FACILITY_ID_<#>
|
PB Standard Only. Each instance of this parameter specifies the ID of a PB Standard facility for which to close out all corresponding shipments. If this parameter is not specified, all shipments for all facilities are closed out. To specify multiple facilities, create a separate object in the
"parameters": [ {
"name": "CARRIER_FACILITY_ID_1",
"value": "1585"
},{
"name": "CARRIER_FACILITY_ID_2",
"value": "1234"
},{
"name": "CARRIER_FACILITY_ID_3",
"value": "6789"
}, ... ]
Important: To close out shipments associated with more than 5 facilities, issue the API call again. To test this parameter in the Sandbox environment, include just one
instance of this parameter and set its value to If you use just once instance of this parameter, specify the parameter as
|
Merchant Object¶
The merchant object appears only in an API response. The object returns information about a merchant.
Name
|
Data Type | Description |
---|---|---|
address | Internal use only. If this field is returned, it is set to null . |
|
company | String | The merchant’s company. |
deactivatedDate | String | For an inactive merchant, the date the merchant’s account was deactivated, returned in the ISO 8601 format. For an active merchant, this field is |
developerId | String | Your Pitney Bowes developer ID. |
String | The merchant’s email address. | |
enterpriseAccount | String | An enterprise account number associated with the merchant. |
fullName | String | The merchant’s full name. |
merchantCarrierAccounts | Array[Object] | Merchants with Multiple Carriers Only. This array appears in the response of the merchant object only if the merchant has registered additional commercial carrier accounts, other than PB Standard or PB Presort. Each object in this array contains information on a specific carrier account. |
accountNumber | String | The merchant’s account number with the carrier. |
carrierName | String | The carrier. Possible values:
|
deactivationDate | Number | If the merchant has removed the carrier account, this field is set to the date that the carrier account was removed. If the carrier account is still active, this field is set to |
isActive | Boolean | If true , the carrier account is active. If false , the merchant has
removed the carrier account. |
isAuthorized | Boolean | If true , the PB Shipping APIs can generate labels with this carrier on
behalf of the merchant. If false , the APIs cannot generate labels with
the carrier for this merchant. |
merchantCarrierAccountAttributes | Array[Object] | Attributes that correspond to settings in the merchant’s carrier account. Each object in the array defines an attribute and its value. |
attributeName | String | The carrier account attribute. |
attributeValue | String | The value of the carrier account attribute. |
registrationDate | Number | The date the merchant’s carrier account was registered for use with Pitney Bowes, shown as milliseconds since the Unix Epoch. |
shipperCarrierAccountId | String | The unique identifier to use when the merchant performs an operation
that uses this carrier account. The identifier is passed in the
X-PB-Shipper-Carrier-AccountId request header of the API request. |
merchantStatus | String | The merchant’s status. Possible values are:
|
merchantStatusReason | String | For an inactive merchant, the reason the merchant was deactivated. For an active merchant, this field is |
merchantType | String | This field is returned only for the Register a Merchant
API call and returns the value KNOWN_SHIPPER . |
parcelProtection | Boolean | If true , the merchant can choose to request PB Parcel Protection coverage when creating a shipment. |
paymentAccountNumber | String | The merchant’s Pitney Bowes payment account number. |
paymentKey | String | If the merchant uses ACH as the payment method, this returns the ACH payment
key. Otherwise this field is null . |
paymentMethod | String | When returned by the Authorize a Merchant
API call, this field indicates the payment method
for the merchant’s PB Postage Account. For other API calls, this field is For the Authorize a Merchant API call, the possible values are:
|
postalReportingNumber | String | The unique ID used to identify the merchant. Note: This value is also the merchant’s Shipper ID. You must specify Shipper ID when creating a shipment. |
registeredDate | Number | The date the merchant’s account was created, shown as milliseconds since the Unix Epoch. You can convert the date to human-readable form by rounding from milliseconds to seconds and then using the Unix timestamp conversion algorithm, or by using a web site that converts milliseconds since the Epoch, such as https://currentmillis.com. |
subscriptionAccount | String | Any subscription account that the merchant might have. |
Parcel Object¶
Name
|
Data Type | Description |
---|---|---|
Weight | Object | Required. The parcel’s weight and unit of measure. |
weight | BigDecimal | Required. The parcel’s weight. |
unitOfMeasurement | String | Required. The unit of measure. Valid values: For USPS shipments, set this to Valid values: |
dimension | Object | Conditional. Defines the parcel’s dimensions. Enter length as the longest dimension, height as the next longest, and width as the shortest. If you enter dimensions differently, the API will reassign them accordingly. For example, if you incorrectly assign the shortest value as the height: "length": "6.0", "width": "4.0", "height": "1.0"
The API will correctly reassign the values to define the shortest value as the width: "length": "6.0", "width": "1.0", "height": "4.0"
Dimensions are required for the following shipments:
However, Pitney Bowes recommends entering dimensions for all shipments. Ensure you enter accurate dimensions. Inaccurate dimensions can lead to additional fees or an undeliverable package. |
length | BigDecimal | The longest dimension. Required by the dimension object. |
height | BigDecimal | The second longest dimension. Required by the dimension object.
Height helps determine a parcel’s girth. |
width | BigDecimal | The smallest dimension. Required by the Note: The PB Shipping APIs will automatically reassign values to ensure width is assigned the smallest dimension. |
unitOfMeasurement | String | The unit of measure. Required by the For USPS shipments, set this to Valid values:
|
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:
For a PB Standard shipment, if you set an irregular parcel girth, then you must
set the IS_RECTANGULAR shipment option to |
valueOfGoods | BigDecimal | Notates the value of the parcel. Important: This value is independent of any values entered for customs or
special services. To declare a value for customs or a special service, you
must declare the value in either the |
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. |
Pickup Object¶
Name | Data Type | Description |
---|---|---|
pickupAddress | Address Object | Required. Pickup Address. |
carrier | String | Required. The carrier for which a pickup is being requested. Set this to: USPS |
pickupSummary | Array[Object] | Required. Each object in the array describes the count and total weight of the parcels for a specific service type. |
serviceId | String | Required. The service type. Valid values are:
|
count | Number | Required. The number of parcels for the service type. This field is used only in the request and is not returned in the response. |
totalWeight | Object | Required. The total weight in ounces for all the parcels for this service type. |
weight | Number, up to 2 decimal places | Required. The total weight in ounces for all the parcels for this service type. |
unitOfMeasurement | String | Required. The unit of measurement. Set this to: OZ |
reference | String | |
packageLocation | String | Required. The location of the parcel at the pickup location. Valid values are:
|
specialInstructions | String | Conditional. Instructions for picking up the parcel. In Production, this is required if the In Sandbox, this field is always required. |
pickupDateTime | String | RESPONSE ONLY. Scheduled date of the pickup. |
pickupConfirmationNumber | String | RESPONSE ONLY. A confirmation number for the pickup. |
pickupId | String | RESPONSE ONLY. The pickup ID. You must specify this ID if canceling the pickup. |
Rates Object¶
Name
|
Data Type | Description |
---|---|---|
carrier | String | Required. Carrier name. Valid values are:
|
serviceId | String | Conditional. The abbreviated name of the carrier-specific service. For abbreviations, see the Services table on the carrier’s reference page. Required for creating a shipment. Optional for rating a parcel. If you use USPS as the carrier:
|
parcelType | String | Conditional. The parcel type. For supported parcel types, see the carrier’s reference page. Required for:
Not applicable to the CBDS Checkout Quotes API. |
specialServices | Array[Special Services Object] | Conditional. The special services to be applied. For available special services and requirements, see the Special Services table on the carrier’s reference page. Important In a Create Shipment request, including a special service in this array means you intend to apply the special service. This array is not applicable to the CBDS Checkout Quotes API. |
inductionPostalCode | String | 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 This field applies to USPS, PB Presort, FedEx, and UPS. |
currencyCode | String | Type of currency referenced in the piece price. For example: This field applies to USPS, CBDS, FedEx, and UPS. |
dimensionalWeight | Object | RESPONSE ONLY. USPS Only. If the Note: A parcel might alternatively be subject to oversize
pricing, as explained in the |
weight | Double | The calculated DIM weight. For information on how USPS calculates DIM weight, see https://www.usps.com/dimensionalweight/. |
unitOfMeasurement | String | The unit of measure for the calculated DIM weight. Possible values:
|
baseCharge | Double | RESPONSE ONLY. The base service charge payable to the carrier, excluding special service charges. This field applies to USPS, CBDS, FedEx, and UPS. USPS: If your request includes a shipper rate plan, see this FAQ on how the shipper rate affects this field. |
totalCarrierCharge | Double | RESPONSE ONLY. The total amount payable to the carrier, including special service fees, surcharges, and any international taxes and duties, except as noted below. This field applies to USPS, CBDS, FedEx, and UPS. USPS: If your request includes a shipper rate plan, see this FAQ on how the shipper rate affects this field. CBDS: In certain cases, the totalCarrierCharge might not reflect additional surcharges. UPS: In Sandbox, the data UPS supplies for
|
surcharges | Array[Object] | RESPONSE ONLY. Additional fees or surcharges for the shipment. Each object in the array defines a surcharge and fee. This field applies to USPS, FedEx, and UPS. |
name | String | The type of surcharge. For possible surcharges, see the carrier’s reference page. |
fee | Double | The amount of the surcharge. |
alternateBaseCharge | Double | RESPONSE ONLY. USPS 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 If the shipper has an NSA, do not use this field. Use the response’s
|
alternateTotalCharge | Double | RESPONSE ONLY. USPS 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 If the shipper has an NSA, do not use this field. Use the response’s
|
deliveryCommitment | Object | RESPONSE ONLY. Time in transit for the shipment. For USPS, see also: Pitney Bowes Delivery Guarantee This field applies to USPS, FedEx, and UPS. |
minEstimatedNumberOfDays | String | The minimum number of delivery days. |
maxEstimatedNumberOfDays | String | The maximum number of delivery days. |
estimatedDeliveryDateTime | String | The estimated delivery date and time in the local time of the destination. |
guarantee | String | States whether carrier delivery is guaranteed. Possible values:
|
additionalDetails | String | These are carrier specific details that may be provided. |
destinationZone | String | RESPONSE ONLY. The destination zone used to determine the rate. The zone is based on the shipment’s origin address or consolidation center and the shipment’s destination address. Note: For CBDS shipments, |
rateTypeId | String | RESPONSE ONLY. The type of rate, such as COMMERCIAL_BASE (USPS) or
COMMERCIAL (FedEx, UPS). |
linePrice | BigDecimal | RESPONSE ONLY. The unit price multiplied by quantity. This field applies to CBDS. |
totalTaxAmount | BigDecimal | RESPONSE ONLY. The total tax amount payable to the carrier. This field applies to CBDS, FedEx, and UPS. |
totalDutyAmount | BigDecimal | RESPONSE ONLY. The total duty amount payable to the carrier. This field applies to CBDS. |
Shipment Object¶
Name | Data Type | Description |
---|---|---|
fromAddress | Address Object | Required. Origin address. If you want a different address to appear on the label from the one listed here, see How do I print a return address that is different from the origin address? |
toAddress | Address Object | Required. Destination address. FedEx, UPS: If you are shipping with FedEx or UPS to Puerto Rico or
an international destination, and if the importer is different from the
final recipient, this is the address of the importer. Enter the recipient’s
address in the |
altReturnAddress | Address Object | USPS, CBDS Only. Applies as follows:
|
parcel | Parcel Object | Required. Contains physical characteristics of the parcel. |
rates | Array[Rates Object] | Required. Specifies the carrier, service, parcel, and other information. In a response, this field also contains the service charges. Important: In a request, the |
documents | Array[Documents Object] | Conditional. Defines the label, manifest, or other shipping document created by the API call. This field is required, except in the following cases:
|
shipmentOptions | Array[Object] | Required. Each object in this array defines a shipment option. Specify each option as a name-value pair in the array. The |
name | String | The name of the shipment option. |
value | String | The value of the shipment option. |
customs | Object | Conditional. For shipments that use customs forms, this object contains the customs information. This field is required for the following carriers in the following situations:
|
customsInfo | Customs Info Object | Customs clearance information used to fill out a commercial invoice. |
customsItems | Array[Customs Items Object] | Information about each commodity in the shipment, used for customs clearance. The maximum number of objects in this array is 30. |
domesticShipmentDetails | Domestic Shipment Details Object | CBDS Only. Required if the merchant prints the first-mile label prior to invoking the Create CBDS Shipment API. This object contains information about the first-mile leg of the shipment. |
soldToAddress | Address Object | FedEx, UPS Only. The final recipient of a the shipment. Required for a shipment from the U.S. to Puerto Rico or to an international destination. Otherwise optional. This address must match the If the final recipient’s address is the same as the importer’s address, the
entries in the |
shipmentType | String | Return Labels Only. Set this to RETURN . Required for Expedited Returns and Standard Returns. |
references | Array[Object] | Merchant-defined values. Applies to the following:
|
hazmatDetails | Hazmat Details Object | PB Standard Only. If shipping hazardous materials with PB Standard, use this object. Use this object only with PB Standard. |
shipmentId | String | RESPONSE ONLY. Unique identifier for the shipment, generated by the system in response to shipment purchase. |
parcelTrackingNumber | String | RESPONSE ONLY. Tracking number assigned to the shipment by the system. |
Shipment Options¶
For the shipment options available for the shipmentOptions
array when creating
or rating shipments, see Shipment Options.
Special Services Object¶
Name | Data Type | Description |
---|---|---|
specialServiceId | String | The abbreviated name of the special service to be applied. For abbreviations, see the Special Services table on the carrier’s reference page. Important Do not include a special service unless you intend to apply it. |
inputParameters | Array[Object] | The parameters, if any, to set for the special service, such as minimum and maximum values. For the available parameters for a special service, see the following:
|
name | String | The name of the input parameter. For USPS, this maps to the
inputParameterRules.name field in the Carrier Rules API. |
value | String | The value of the parameter. For USPS, 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. |
Transaction Object¶
Name | Data Type | Description |
---|---|---|
transactionId | String | The ID used to uniquely identify the shipment associated with the
transaction. The ID is a combination of the developer ID and the
shipment’s
|
transactionDateTime | String | The date and time of the transaction, returned in UTC/GMT using the ISO 8601 standard. |
transactionType | String | Type of transaction. Valid values:
|
developerName | String | Name of the developer account used to print the shipment label. |
developerId | String | The developer ID used to print the shipment label. |
developerPostagePaymentMethod | String | The developer’s PB Postage Account payment method. This is populated only for transactions that use the Bulk Postage Account payment model, as described in Merchant Enrollment Models. |
developerRatePlan | String | Rate plan of the developer (integrator). |
developerRateAmount | String | Amount charged to the developer. The amount is based on the developer’s rate plan. If the merchant (shipper) has an NSA, the amount is instead based on the NSA. APV Adjustments: If the transaction is an APV adjustment, this field is the difference between the charge that was calculated at the time of print and the charge calculated by USPS®. |
developerPostagePaymentAccountBalance | String | This field is not currently used. |
merchantName | String | Name of the merchant. |
merchantId | String | The value of the postalReportingNumber field in the Merchant
object. This value is also the merchant’s
Shipper ID. |
merchantPostageAccountPaymentMethod | String | The merchant’s PB Postage Account payment method. This is populated only for transactions that use the Individual Postage Account payment model, as described in Merchant Enrollment Models. |
merchantRatePlan | String | Rate plan of the merchant (shipper). |
merchantRate | String | Amount charged to the merchant. This is based on the merchant’s shipper rate plan. APV Adjustments: If the transaction is an APV adjustment, this field is the difference between the charge to the merchant calculated at the time of print and the charge calculated based on information from USPS. |
shipperPostagePaymentAccountBalance | String | Postage balance in the merchant’s PB Postage Account. This is the ending balance after this transaction was processed. If the merchant’s postage balance is currently negative, the merchant must refill the postage account. See How do I fill my PB Postage Account with funds? |
labelFee | String | Currently not used. |
parcelTrackingNumber | String | Tracking number. |
weightInOunces | String | Weight in ounces. In the case of an APV adjustment, this is based on the new information received from USPS. |
zone | String | Zone. In the case of an APV adjustment this is based on the new information received from USPS. |
packageLengthInInches | String | Package length in inches. In the case of an APV adjustment, this is based on the new information received from USPS. |
packageWidthInInches | String | Package width in inches. In the case of an APV adjustment, this is based on the new information received from USPS. |
packageHeightInInches | String | Package height in inches. In the case of an APV adjustment, this is based on the new information received from USPS. |
packageTypeIndicator | String | Indicates whether cubic pricing was used. Valid values:
In the case of an APV adjustment, this is based on the new information received from USPS. |
packageType | String | The parcel type. For supported parcel types, see the carrier’s reference page. In the case of an APV adjustment, this is based on the new information received from USPS. |
mailClass | String | Mail class or service. |
internationalCountryGroup | String | International country group code. |
originationAddress | String | Origination address. |
originZip | String | Origin postal code. |
destinationAddress | String | Destination address. |
destinationZip | String | Destination postal code. |
destinationCountry | String | Destination country. |
postageDepositAmount | String | Postage deposit amount. |
creditCardFee | String | Credit card fee. |
refundStatus | String | Refund status. Possible values include:
For more information on refunds, see Refunds FAQs. |
refundDenialReason | String | The reason for a refund denial. |
printStatus | String | This field is not currently used. |
shipmentId | String | The unique identifier for the shipment generated when the shipment was created. |
refundRequestor | String | Indicates who requested the refund.
|
externalId | String | Applies only to the following:
|
adjustmentReason | String | APV Only. The reason for an APV adjustment, based on information received from USPS. Possible values are:
|
meterNumber | String | Internal identification number for the postage meter that was used. |
dimensionalWeightOz | BigDecimal | The dimensional weight, if applicable. To return this field, set the This field applies to API v4.0 or higher. |
valueOfGoods | BigDecimal | The value provided in the To return this field, set the This field applies to API v4.0 or higher. |
specialServices | Array[Special Services Object] | This array contains the shipment’s special services, including the fee paid for each service. To return this field, set the This field applies to API v4.0 or higher. |
status | String | The transaction status for the following types of transactions:
This field applies to API v4.0 or higher. |
description | String | Details on the status of an ACH transaction. Possible values:
This field applies to API v4.0 or higher. |
inductionPostalCode | BigDecimal | The postal code where the shipment was tendered to the carrier. To return this field, set the This field applies to API v4.0 or higher. |
tracking | Object | Applies to Transaction Reports Only. This object does not apply to Archived Reports. For a This object applies to API v4.0 or higher. |
parcelStatus | String | The most recent tracking event within 30 days of the parcel’s ship date.
This is the same information returned in the Note: Transaction Reports record tracking status only for the first 30 days after the parcel’s ship date. This field applies to API v4.0 or higher. |
statusDate | String | The local date and time where the tracking event occurred. This is the same
information returned in This field applies to API v4.0 or higher. |
customMessage1 | String | The message specified in the PRINT_CUSTOM_MESSAGE_1 shipment option in the Create Shipment request. To return this field, set the This field applies to API v4.0 or higher. |
customMessage2 | String | The message specified in the PRINT_CUSTOM_MESSAGE_2 shipment option in the Create Shipment request. To return this field, set the This field applies to API v4.0 or higher. |