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

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

Required if specified as such on the API request’s documentation page.

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

The city or town.

Required if specified as such on the API request’s documentation page.
stateProvince String

The state or province. For a US or Canadian address, use the 2-letter state or province code.

Required if specified as such on the API request’s documentation page.
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.

Required if specified as such on the API request’s documentation page.
countryCode String

Two-character country code from the ISO country list.

Required if specified as such on the API request’s documentation page.
company String

The name of the company.

Required if specified as such on the API request’s documentation page.
name String

The first and last name.

Required if specified as such on the API request’s documentation page.
phone String

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

Required if specified as such on the API request’s documentation page.
email String

The email address.

Required if specified as such on the API request’s documentation page.
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. Indicates whether the address is valid and whether the validation check made changes to the address.

Note: The response does not return this field if minimal address validation is enabled.

Possible values are:

  • VALIDATED_CHANGED: The address is valid. The validation check made changes to the address.
  • VALIDATED_AND_NOT_CHANGED: The address is valid. No changes were made.
  • NOT_CHANGED: The address could not be validated. No changes were made.

 

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 if you use the descriptions array.
        name String The category description. The maximum length is 255 characters. Required in 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 (|) delimiter. For example:

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

Type of currency referenced in the piece price. Use three uppercase letters, per ISO 4217. For example: USD, CAD, EUR.

Required for CBDS.
businessType String

CBDS Only. For merchants who use the CBDS Quotes API, enter the type of transaction. Valid values are:

  • B2B
  • B2C (Default)
customsDeclaredValue BigDecimal The value of the item that is going to be declared in customs.
EELPFC
String

A number provided by the Automated Export System (AES).

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 Quotes API and the drop-off solution, the insurance cost associated with bringing the parcel to the Pitney Bowes facility.

For merchants who use the end-to-end solution, please see the insuredAmount field instead of this field.
firstMileShippingAmount BigDecimal

CBDS Only. For merchants who use the CBDS Quotes API and the drop-off solution, the shipping cost associated with bringing the parcel to the Pitney Bowes facility.

For merchants who use the end-to-end solution, please see the shippingAmount field instead of this field.
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

A reference number used by the importer. For example, a PO number or insured number.

Required for shipments to Brazil: For goods sent to Brazil, this field is required. 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 (FCPIS), set the label size to DOC_8X11. See also: Where is the Importer’s Tax ID displayed on a Customs form?
insuredAmount BigDecimal

CBDS & FedEx Only. The insurance fee:

  • CBDS: For merchants who use the CBDS Quotes API and the end-to-end solution, enter the full end-to-end insurance cost, if applicable. The cost entered is used for duty and tax calculation. Enter the value in the currency specified in currencyCode.

    For merchants who use the drop-off solution, please see the firstMileInsuredAmount field instead of this field.

  • For FedEx: Enter the fee for the purchased insurance. This field prints the fee on the FedEx Commercial Invoice. Make sure to enter the fee for the purchased insurance, not the coverage amount. This field is optional.

Note: If this field appears in the response for a carrier other than the above, it will have a value of 0.0 and can be ignored.
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 freightCharge, handlingCosts, insuredAmount, or packingCosts fields. 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.
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 Only. For merchants who use the CBDS Quotes API, 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, if a shipment is destined for Germany but cleared for customs in France, this field would take a value of FR, for France. If port of clearance and destination are the same country, this field can be left blank.

Required for merchants who use the CBDS digital-only solution.
reasonForExport String

The reason the commodity is being exported. Valid values are:

  • GIFT
  • COMMERCIAL_SAMPLE
  • MERCHANDISE
  • DOCUMENTS
  • RETURNED_GOODS
  • OTHER

Note: First-Class Mail International (FCMI) shipments can contain only documents, not goods. For FCMI, set this field to DOCUMENTS. Goods can be shipped via First-Class Package International Service (FCPIS) and other services.
reasonForExportExplanation String

The reason the commodity is being exported.

Required if the reasonForExport field is set to OTHER.
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 Only. For merchants who use the CBDS Quotes API and the end-to-end solution, enter the end-to-end shipping cost, for use in duty and tax calculation. Enter the value in the currency specified in currencyCode.

For merchants who use the drop-off solution, please see the firstMileShippingAmount field instead of this field.
shippingDocumentType String UPS Only.
termsOfSale String UPS Only.

 

Customs Items Object

The fields are listed alphabetically. The carriers that use a field are identified by name and color: USPS, CBDS, FedEx, UPS. Note that CBDS uses a rates.carrier value of PBI.

Name
Data Type
Description
brand String

The manufacturer’s brand name for the item. The maximum length is 255 characters.

Applies to: CBDS
categories Array[Categories Object]

Associated categories. The merchants category tree must have been provided to Pitney Bowes in advance. Do not use this array if the category tree has not been provided in advance.

Required for the CBDS HS Code API. Optional for other CBDS APIs.

Applies to: CBDS
condition String

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:

  • new
  • used
  • refurbished
  • damaged
  • unknown

Applies to: CBDS
description String

A detailed description of the commodity.

For the PB Cross-Border Delivery Service (CBDS), which uses a carrier value of PBI, make the description as detailed as possible to facilitate assignment of the correct HS Code.

Required for all APIs that use customsItems.

Applies to: USPS, CBDS, FedEx, UPS
eccn String

The Export Control Classification Number (ECCN) for the commodity. The maximum length is 10 characters.

Applies to: CBDS
hazmats Array[String]

The identification of a HAZMAT-flagged item. For valid values please see HAZMAT-flagged Items

Applies to: CBDS
hSTariffCode String

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 CBDS HS Code API, you can use this field to help with the prediction by entering the commodity’s HS Code from another country, such as from the origin country. Set the country the code comes from in the hSTariffCodeCountry field.

Required for the CBDS Quotes API for clients using Pitney Bowes’s digital-only services and not using the logistics network.

Applies to: USPS, CBDS, FedEx, UPS
hSTariffCodeCountry String

The two-character ISO country code for the destination country.

Required for CBDS if the hSTariffCode field is used.

Applies to: CBDS
identifiers Array[Object]

Additional identifiers for the item. For example:

Applies to: CBDS
      number String

The value of the identifier. The maximum length is 50 characters.

Required by the identifiers array.

Applies to: CBDS
      source String

The type of identifier, such as MPN, SKU, UPC, ISBN, or ISSN. The maximum length is 10 characters.

Required by the identifiers array.

Applies to: CBDS
imageURL Array[String]

URLs to images of the commodity.

Applies to: CBDS
itemDimension Object

The dimensions for a single item.

Applies to: CBDS
      length BigDecimal

The longest dimension.

Required by the itemDimension object.

Applies to: CBDS
      height BigDecimal

The second longest dimension.

Required by the itemDimension object.

Applies to: CBDS
      width BigDecimal

The shortest dimension.

Required by the itemDimension object.

Applies to: CBDS
      unitOfMeasurement String

The unit of measurement. Valid values are:

  • IN: Inches
  • FT: Feet
  • YD: Yards
  • CM: Centimeters
  • M: Meters

Required by the itemDimension object.

Applies to: CBDS
itemId String

The merchant’s unique identifier for the commodity, such as an SKU. The maximum length is 50 characters.

Required for CBDS APIs.

Applies to: CBDS
manufacturer String

The manufacturer of the item. The maximum length is 255 characters.

Applies to: CBDS
netCostMethod String Applies to: UPS
originCountryCode String

The two-character ISO country code of the shipment’s origin country. Use ISO 3166-1 alpha-2 standard values.

Applies to: USPS, CBDS, FedEx, UPS
originStateProvince String Applies to: UPS
preferenceCriterion String Applies to: UPS
pricing Object

The pricing information for the commodity. If the information is not in the shopping cart, then this information is used.

Applies to: CBDS
      price BigDecimal

List price of the item.

Applies to: CBDS
producerAddress Address Object Applies to: UPS
producerDetermination String Applies to: UPS
producerId String Applies to: UPS
quantity Integer

The total number of items of this type of commodity.

If you use USPS is the carrier, the number of items of one commodity cannot exceed 9999. USPS limits the number of items of one commodity to 9999.

Required for all APIs that use customsItems, except for the CBDS HS Code API.

Applies to: USPS, CBDS, FedEx, UPS
quantityUOM String Applies to: UPS
unitPrice BigDecimal

The price of one item of this type of commodity.

Required for all APIs that use customsItems.

Applies to: USPS, CBDS, FedEx, UPS
unitWeight Object

The weight of one item of this type of commodity.

Required for all international shipments, except for CBDS shipments, for which the field is optional.

Applies to: USPS, CBDS, FedEx, UPS
      weight Number

The weight in the units specified in the unitOfMeasurement field.

Required by the unitWeight object.

Applies to: USPS, CBDS, FedEx, UPS
      unitOfMeasurement String

The unit of measurement. If USPS is the carrier, set this to OZ. This field can take the following values:

  • OZ: Ounces
  • GM: Grams
  • G: Grams. Available for CBDS APIs only.
  • LB: Pounds. Available for CBDS APIs only.
  • KG: Kilograms. Available for CBDS APIs only.

Required by the unitWeight object.

Applies to: USPS, CBDS, FedEx, UPS
url String

The commodity’s URL on the merchant’s site. Ensure the URL works. Providing a accurate URL helps Pitney Bowes assign the correct HS Code. The maximum length for this field is 1000 characters.

Recommended for CBDS APIs that use customsItems.

Applies to: CBDS

 

Documents Object

Name Data Type Description
type String

The type of document. Valid values are:

  • SHIPPING_LABEL: Returns a shipping label.
  • QR_CODE: Available for PB Standard Returns only. Returns a QR Code that prints a shipping label.
  • MANIFEST: Returns an end-of-day manifest.
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:

  • DOC_4X4
  • DOC_4X5
  • DOC_4X6
  • DOC_4X8
  • DOC_6X4
  • DOC_8X11
  • DOC_9X4
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:

  • URL: The response returns a link to the label or manifest.
  • BASE64: Available for shipping labels only. The response returns the shipping label as one or more Base64-encoded strings. If you use an APAC URI, the field instead returns raw ZPL, as described in Label Settings for APAC Services.
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:

  • PDF
  • PNG. Available for shipping labels only.
  • ZPL2. Available for shipping labels only. 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. If you use this value, the documents.type field must be set to QR_CODE.
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:

  • DPI_203: Label uses 203 DPI
  • DPI_300: Label uses 300 DPI
printDialogOption String

Conditional. 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. This field is required for USPS, PB Expedited Returns, and PB Standard Returns, and for Create CBDS Shipments API calls that print a label.

Valid values are:

  • 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.
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 docTab.name is set to a field returned by the Create Shipment API, this defines how the field name is displayed on the label.

For example, if you set the following:

{ "name": "parcelTrackingNumber", "displayName": "Tracking Number" }

The label will display:

Tracking Number: <parcelTrackingNumber>

where <parcelTrackingNumber> is the value of the parcelTrackingNumber field.

If you don’t define a displayName, the actual field name is used.
      value String

To display a field and value that are not returned by the Create Shipment API, enter the new name in the docTab.name field and enter the value here. For example:

{ "name": "DiscountCode", "value": "JUN40" }
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, 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:

  • USPS
  • DHL: DHL Express
  • FedEx
  • UPS
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.

 

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:

  • USPS
  • NEWGISTICS. PB Standard. This value is valid only in a Create Manifest request.
  • PBPresort. This value is valid only in a Create Manifest request.
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 carrier field is set to NEWGISTICS, use the long version of the tracking number.
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 postalReportingNumber field.
MANIFEST_TYPE

Specifies the type of manifest.

Required if creating a PMOD manifest (PS Form 3152).

Valid values are:

  • PMOD: Creates a PS Form 3152 for PMOD shipments.
  • NORMAL: For USPS and PB Presort this creates the correct form for the carrier. This is the default setting for those carriers. The parameter can be left out of the API call.
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 NGST.

Required for PB Standard manifest requests.

CARRIER_FACILITY_ID_<#>
where <#> is an integer from 1 to 5.

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 array for each instance of this parameter, up to five objects. Start with CARRIER_FACILITY_ID_1 and increment by 1 up to CARRIER_FACILITY_ID_5. For example:

"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 1585.

If you use just once instance of this parameter, specify the parameter as CARRIER_FACILITY_ID_1.

 

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 null.
developerId String Your Pitney Bowes developer ID.
email 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:

  • FEDEX
  • UPS
    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 0.
    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:

  • ACTIVE
  • INACTIVE
merchantStatusReason String

For an inactive merchant, the reason the merchant was deactivated.

For an active merchant, this field is null.
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 null.

For the Authorize a Merchant API call, the possible values are:

  • LineOfCredit/Prepaid: PB Line of Credit
  • CreditCard: U.S. credit card
  • ACH: (Automated Clearing House)
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 OZ.

Valid values:

  • OZ: Ounces
  • GM: Grams
  • LB: Pounds. Available only for CBDS.
  • KG: Kilograms. Available only for CBDS.
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:

  • USPS shipments that use Parcel Select or use soft pack envelopes. However, USPS encourages shippers to provide dimensions for all packages.
  • PB Standard.
  • PB Presort

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 dimension object. Width helps determine a parcel’s girth.

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 dimension object.

For USPS shipments, set this to IN.

Valid values:

  • IN: inches
  • CM: centimeters
    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.
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 customs.customsInfo object or the rates.specialServices array.
currencyCode String ISO Currency Code. Use three uppercase letters, per ISO 4217. For example: USD, CAD, EUR.

 

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:

  • FCM: First-Class Mail
  • PM: Priority Mail
  • EM: Priority Mail Express
  • PRCLSEL: Parcel Select
  • INT: Indicates one of the following international services: First-Class Mail International; First-Class Package International Service; Priority Mail Express International; Priority Mail International
  • OTH: Other Packages
    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:

  • Front Door
  • Back Door
  • Side Door
  • Knock on Door/Ring Bell
  • Mail Room
  • Office
  • Reception
  • In/At Mailbox
  • Other
specialInstructions String Conditional. Instructions for picking up the parcel. Required if packageLocation is set to Other.
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:

  • USPS
  • NEWGISTICS: PB Standard. This value is available only for Create Shipment requests.
  • PBPRESORT: This value is available only for Create Shipment requests.
  • PBI: PB Cross-Border Delivery Service (CBDS)
  • FEDEX
  • UPS
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:

  • To determine any additional restrictions on a USPS service, use the Carrier Rules API. See also the USPS Domestic Mail Manual.
  • The PB Shipping APIs require that all USPS parcels be trackable. If the parcel uses a service that is not trackable, such as Priority Mail, you must add at least one trackable special service, such as Delivery Confirmation (DelCon). DelCon is a no-charge special service that triggers tracking but does not increase the cost of the shipment. Before adding a special service, check its compatibility with the service.
parcelType String

Conditional. The parcel type. For supported parcel types, see the carrier’s reference page.

Required for:

  • Creating a shipment
  • Rating a FedEx or UPS parcel

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

This field applies to USPS, PB Presort, FedEx, and UPS.
currencyCode String

Type of currency referenced in the piece price. For example: USD, CAD, EUR

This field applies to USPS, CBDS, FedEx, and UPS.
dimensionalWeight Object

RESPONSE ONLY. USPS Only. If the dimensionalWeight.weight field has a value other than 0, dimensional-weight pricing applies to the shipment. In general, if a parcel is large and relatively light for its size, it might be subject to dimensional-weight pricing. Dimensional weight, or DIM weight, is calculated based on volume and a volumetric divisor. For information on how USPS calculates DIM weight, see https://www.usps.com/dimensionalweight/.

Note: A parcel might alternatively be subject to oversize pricing, as explained in the surcharges field below.
    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:

  • GM: Grams
  • OZ: Ounces
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 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.
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 X-PB-Shipper-Rate-Plan parameter.

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. 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 X-PB-Shipper-Rate-Plan parameter.

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

  • FULL
  • NONE
    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, destinationZone is returned as a Number.
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 soldToAddress object. If importer’s address is the same as the final recipient, the toAddress and soldToAddress must match.
altReturnAddress Address Object

USPS, CBDS Only. Applies as follows:

  • USPS: If you are sending an international shipment through USPS and if you have set the NON_DELIVERY_OPTION shipment option to redirect, then enter the address that a returned parcel should go to.
  • CBDS: For a Create Shipment request, this is the address used to return a parcel from the CBDS Consolidation Center. If omitted, the fromAddress is used. The altReturnAddress is not returned in the response.
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 rates array can contain only one rates object.
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:

  • This field does not apply to Rate Parcel requests.
  • This field does not apply to the Create CBDS Shipment request if the merchant prints the first-label prior to invoking the API.
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 SHIPPER_ID option is required. For any additional requirements for a carrier or service, please see the Things to Consider section on the carrier’s Create Shipment page.
        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:

  • USPS: Required for shipments to international destinations or to APO/FPO/DPO, Territories/Possessions, or FAS.
  • CBDS: Required for all shipments.
  • FedEx: Required for shipments to international destinations and Puerto Rico.
  • UPS: Required for shipments to international destinations and Puerto Rico.
        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 toAddress.countryCode, with the exception of shipments to Canada and to U.S. satellite countries.

If the final recipient’s address is the same as the importer’s address, the entries in the soldToAddress object must match the entries in the toAddress object.
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:
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 X-PB-TransactionId, separated by an underscore (_):

<Developer-ID>_<X-PB-TransactionId>
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:

  • POSTAGE FUND: The funding of a postage account.
  • POSTAGE PRINT: The printing of a label.
  • POSTAGE REFUND: A refund request or the resolution of a refund request.
  • FEE: An ACH return fee. The status field indicates whether the fee is processed or waived.
  • APV-POSTAGE OVERPAID: An APV adjustment for overpayment.
  • APV-POSTAGE UNDERPAID: An APV adjustment for underpayment.
  • APV-DISPUTE ADJUSTMENT: A dispute of an APV-POSTAGE UNDERPAID transaction.
  • CREDIT ADJUSTMENT: A manual credit.
  • DEBIT ADJUSTMENT: A manual debit.
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:

  • Cubic
  • NonCubic

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:

  • REQUESTED
  • ACCEPTED
  • DENIED

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.

  • Shipper Requested: The shipper requested the refund.
  • PB Claims: The request is part of the Delivery Guarantee program.
externalId String

Applies only to the following:

  • APV adjustments: The USPS Revenue Assurance ID assigned to the APV adjustment in case of a dispute.
  • PB Delivery Guarantee: This is an ID beginning with “PBD” and followed by sequence of numbers. This indicates a Delivery Guarantee credit.
adjustmentReason String

APV Only. The reason for an APV adjustment, based on information received from USPS. Possible values are:

  • weight. Incorrect weight listed when creating the label.
  • dimension: Incorrect dimensions listed when creating the label.
  • package: Incorrect parcel type listed when creating the label.
  • zone: Incorrect origin or induction postal code listed when creating the label.
  • duplicate: The label had already been inducted. The IMpb tracking barcode was entered into the USPS mailstream more than once within 120 days. The transaction report includes the charges for the additional use of the label.
  • usedRefundedLabel: The label was a refunded label that was then entered into the USPS mailstream. The transaction report includes the charges for using the label after having voided it.
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 shipDetails query parameter to 1.

This field applies to API v4.0 or higher.
valueOfGoods BigDecimal

The value provided in the parcel.valueOfGoods field in the Create Shipment request, if applicable.

To return this field, set the shipDetails query parameter to 1.

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 shipDetails query parameter to 1.

This field applies to API v4.0 or higher.
status String

The transaction status for the following types of transactions:

  • ACH transaction. Possible values:
    • Pending: A POSTAGE FUND transaction is pending.
    • Processed: Either a POSTAGE FUND or a FEE transaction has been processed.
    • Returned: A POSTAGE FUND transaction failed.
    • Waived: A FEE has been waived.
  • APV dispute. Possible values:
    • REQUESTED
    • ACCEPTED
    • DENIED
  • Expedited Returns label. Possible values:
    • Printed
    • Charged

This field applies to API v4.0 or higher.
description String

Details on the status of an ACH transaction. Possible values:

  • Postage Fund Pending: A POSTAGE FUND transaction is pending.
  • Postage Fund Processed: A POSTAGE FUND transaction has been processed.
  • Postage Fund Returned: A POSTAGE FUND transaction failed.
  • ACH Return Fee Processed: A FEE has been processed.
  • ACH Return Fee waived: A FEE has been waived.

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 shipDetails query parameter to 1.

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 POSTAGE PRINT transaction, this object returns the most recent tracking event within 30 days of the transaction’s date and time. To return this object, include the trackingStatus query parameter in the request.

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 status field of the Tracking API.

Note: Transaction Reports do not record tracking events that occur 30 days or more after the parcel’s ship date. In Transaction Reports, the most recent tracking event will always be within 30 days of the 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 updatedDate and updatedTime in the Tracking API.

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 shipDetails query parameter to 1.

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 shipDetails query parameter to 1.

This field applies to API v4.0 or higher.