Resource Objects for the Shipping and Accounts APIs

This page describes common JSON objects used by the Shipping and Accounts APIs. For objects not listed here, see the specific API operation. For the common resource objects used by the Fulfillment APIs, click here.

Object

Description

Address

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

Customs

Customs-clearance information.

Customs Info

Customs-clearance information.

Customs Items

Customs-clearance information.

Dimension

Parcel dimensions.

Documents

The shipment documents, including the label.

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.

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

Important

For the required fields in this object, see the Considerations section on the API request’s documentation page.

Name

Data Type

Description

addressLines

Array[String]

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

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

Required if specified in Considerations on the API documentation page.

cityTown

String

The city or town.

Required if specified in Considerations on the API 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 in Considerations on the API 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 in Considerations on the API documentation page.

countryCode

String

Two-character country code from the ISO country list.

Required if specified in Considerations on the API documentation page.

company

String

The name of the company.

Required if specified in Considerations on the API documentation page.

name

String

The first and last name.

Required if specified in Considerations on the API 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 in Considerations on the API documentation page.

email

String

The email address.

Required if specified in Considerations on the API documentation page.

residential

Boolean

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

Required for APAC Services.

deliveryPoint

String

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

carrierRoute

String

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

taxId

String

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

status

String

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

Possible values are:

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

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

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

 

Customs Object

Name

Data Type

Description

customsInfo

Customs Info Object

Customs clearance information used to fill out a commercial invoice.

customsItems

Array[Customs Items Object]

Customs clearance information about each commodity.

 

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. The full list of currency codes can be downloaded in XLS or XML from https://www.iso.org/iso-4217-currency-codes.html.

If you are creating a CBDS shipment, set this field as follows: For U.S. outbound, USD; For UK outbound, GBP; For Canada outbound and Canada domestic, CAD.

businessType

String

CBDS Quotes API Only. Enter the type of transaction. Valid values are:

  • B2B

  • B2C (Default)

customsDeclaredValue

BigDecimal

Enter the value to declare in customs for the shipment. Enter the value in the currency specified in the currencyCode field.

Required for FedEx.

Do not use this field with PB Expedited.

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 Quotes API Only. If the merchant uses a Drop-Off delivery 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 Quotes API Only. If the merchant uses a Drop-Off delivery 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

A reference number used by the importer, such as a VAT number, PO number, or insured number. Pitney Bowes does not print the number on the customs form.

Required for shipments to the EU from outside the EU. Enter a VAT or IOSS number. Specify which type of number in the importerCustomsReferenceType field.

Required for shipments to Brazil. Enter the Importer’s Tax Identification 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?

Do not use this field for CBDS. CBDS automatically provides the IOSS number.

importerCustomsReferenceType

String

Required if you enter a VAT or IOSS number in the importerCustomsReference field. Specify which type of number you entered:

  • VAT_NUMBER

  • IOSS_NUMBER

insuredAmount

BigDecimal

CBDS and FedEx Only. Enter the insurance fee, if applicable. This field is used as follows:

  • CBDS: This field applies only to the CBDS Quotes API. Enter the full end-to-end insurance fee, if applicable. The value is used in the duty-and-tax calculation for countries that include the fee in the calculation.

    Required if an insurance fee applies and the merchant uses the CBDS digital-only solution (i.e., the merchant does not ship via CBDS).

  • FedEx: This field prints the insurance fee on the FedEx Commercial Invoice. Enter the fee for the purchased insurance. Do not enter coverage amount.

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 Quotes API Only. 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 NL if a shipment destined for Germany is cleared for customs in the Netherlands. This field is required if the port of clearance is different and the merchant uses the CBDS digital-only solution (i.e., the merchant does not ship via CBDS).

If the port of clearance and destination country are the same, leave this field blank.

reasonForExport

String

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

  • GIFT

  • COMMERCIAL_SAMPLE

  • MERCHANDISE

  • DOCUMENTS (If using this value, see also this related FAQ)

  • RETURNED_GOODS

  • OTHER

Required for PB Expedited (USPS) and UPS.

Note: For USPS First-Class Mail International (FCMI), you must set this field to DOCUMENTS. FCMI cannot ship goods. To ship goods through USPS, you can use First-Class Package International Service (FCPIS) or other services.

reasonForExportExplanation

String

The reason the commodity is being exported.

Required for PB Expedited 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 Quotes API Only. Enter the end-to-end shipping 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.

Required if the merchant uses the CBDS digital-only solution (i.e., the merchant does not ship via CBDS).

shippingDocumentType

String

UPS Only.

termsOfSale

String

UPS Only.

 

Customs Items Object

The following table lists the fields alphabetically.

Name

Data Type

Description

brand

String

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

Maximum length: 255 characters

categories

Array[Categories Object]

CBDS Only. This array is used by the HS Code API.

Required for 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:

  • new

  • used

  • refurbished

  • damaged

  • unknown

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.

Maximum length: 10 characters

hazmats

Array[String]

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

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.

Required for the Shopping Cart Quotes API.

If you are using the Predicted HS Code API, you can supply the HS code from another country in this field to help with the prediction. See the instructions in the API’s Considerations.

Maximum length: 14 characters

hSTariffCodeCountry

String

CBDS Only. The two-character ISO Country Code for the country supplying the HS code. This is usually the destination country.

Required if the hSTariffCode field is used.

identifiers

Array[Object]

CBDS Only. Additional identifiers for the item. Each object in the array defines a type of identifier and its value.

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

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

Dimension Object

CBDS Only. The dimensions for a single item.

itemId

String

CBDS Only. Required. The merchant’s unique identifier for the commodity, such as the SKU or item code. The value might be used to verify the product during customs clearance. To avoid shipment delays, the value should be unique for individual variants of a product.

To avoid problems processing the order data, make sure the value does not include leading or trailing spaces.

Maximum length: 50 characters

manufacturer

String

CBDS Only. The manufacturer of the item.

Maximum length: 255 characters

netCostMethod

String

UPS Only.

originCountryCode

String

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

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.

pricing.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 PB Expedited (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, except for CBDS. The weight and unit of measure of one item of the commodity.

Note: This field is optional for CBDS.

unitWeight.weight

Number

The weight of the item. This field is required by the unitWeight object.

unitWeight.unitOfMeasurement

String

The unit of measurement. This field is required by the unitWeight object. If the carrier is PB Expedited (USPS), set this to OZ. This field can take the following values:

  • OZ: Ounces

  • GM: Grams

The following values are available only for CBDS:

  • G: Grams

  • LB: Pounds

  • KG: Kilograms

url

String

CBDS Only. Required. Enter the commodity’s URL on the merchant site. Ensure the URL works. Providing an accurate URL helps Pitney Bowes assign the correct HS code.

Maximum length: 1000 characters

 

Dimension Object

Name

Data Type

Description

length

BigDecimal

Required. The longest dimension.

Entering Dimensions: In the Dimension object, enter length as the longest dimension, height as next longest, and width as shortest. If you enter dimensions differently, the API will reassign them accordingly. For example, if you have a parcel that measures 6 x 4 x 1 inches, and if you assign 1 inch to the height:

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

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

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

height

BigDecimal

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

For the order of dimensions, see Entering Dimensions above.

width

BigDecimal

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

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

unitOfMeasurement

String

Required. The unit of measure. Valid values:

  • IN: Inches (Required for PB Expedited)

  • CM: Centimeters

The following values are available only for CBDS international shipments:

  • FT: Feet

  • YD: Yards

  • M: Meters

irregularParcelGirth

String

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

girth = 2 * (height+width)

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

Documents Object

Name

Data Type

Description

type

String

The type of document. Possible values:

  • SHIPPING_LABEL: Returns a shipping label.

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

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

Required for CBDS shipments.

size

String

The recommended size of the label. The actual size of a label depends on the carrier. For valid values for your API call, see the Labels section on the carrier page of the carrier you are using. The field takes the following values, though valid values depend on your API call:

  • DOC_4X4

  • DOC_4X5

  • DOC_4X6

  • DOC_4X8

  • DOC_6X4

  • DOC_8X11

  • DOC_9X4

Required if the type field is set to SHIPPING_LABEL or if the shipment is a CBDS shipment.

contentType

String

Determines whether the API returns the document as a URL or a Base64-encoded string. For valid values for your API call, see the Labels section on the carrier page of the carrier you are using. The field takes the following values, though valid values depend on your API call:

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

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

Required for PB Expedited, PB Standard, PB Presort, CBDS, and PMOD. For PMOD, this field is optional if fileFormat is set to PDF.

fileFormat

String

The file format for the document. For valid values for your API call, see the Labels section on the carrier page of the carrier you are using. The field takes the following values, though valid values depend on your API call:

  • PDF

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

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

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

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

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

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

resolution

String

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

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

For valid values for your API call, see the Labels section on the carrier page of the carrier you are using. The field takes the following values, though valid values depend on your API call:

printDialogOption

String

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

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

  • NO_PRINT_DIALOG: No print dialog box is rendered.

Required for the following shipments:

  • PB Expedited Returns

  • PB Standard Returns

  • CBDS Shipments that print a label (see CBDS Delivery Options).

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?

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

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

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

pages.contents

String

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

customerData

Customer Data Object

PB Standard Returns Only. This object is used to:

  • Print custom barcodes, which all PB Standard Returns merchants can do. See Custom Barcodes.

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

Documents: Customer Data Object

Name

Data Type

Description

labelDetails

Array[Object]

The name-value pairs in this array pass the parameters and values used to print custom barcodes or to perform other custom functions.

labelDetails.name

String

The parameter.

labelDetails.value

String

The parameter’s value.

 

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: PB Expedited or PMOD

  • PBCS: PB Standard

  • PBPresort: PB Presort

submissionDate

String

Required. The date the shipments are to be tendered to the carrier, entered as YYYY-MM-DD.

fromAddress

Address Object

The shipment origin address.

Required for:

inductionPostalCode

String

Postal code where the shipments are tendered to the carrier.

Do not use for PB Standard manifests. The field does not apply.

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 PBCS, use the long version of the tracking number.

parameters

Array[Object]

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

parameters.name

String

The name of the manifest parameter.

parameters.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. The manifest tracking number. This is returned only if carrier has a value of USPS.

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:

  • NORMAL: For PB Expedited, PB Presort, and PMOD 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.

  • PMOD: Creates a PS Form 3152 for PMOD shipments.

CLIENT_ID

PB Standard Only. The merchant’s unique PB Standard client ID assigned when the merchant onboarded with PB Standard.

Required for PB Standard manifest requests.

If testing an API operation in Sandbox, use the Sandbox value listed on the operation’s documentation page.

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 use the Sandbox value listed on the operation’s documentation page.

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

 

Merchant Object

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[Merchant Carrier Accounts 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.

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

Indicates the type of merchant:

paymentAccountNumber

String

The identifier for the PB Postage Account.

paymentServicesAccountId

String

A UUID that identifies the payment services account used to fund the merchant’s PB Postage Account. The payment services account has the merchant’s payment methods. A merchant can have one or more payment methods.

paymentServicesAccountIdActive

Boolean

If set to true, the merchant’s payment services account is active and can be used to fund postage.

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.

paymentMethod

String

When returned by the Authorize a Merchant API, this indicates the payment method for the merchant’s PB Postage Account. Possible values are:

  • LineOfCredit/Prepaid: PB Line of Credit

  • CreditCard: U.S. credit card

  • ACH: Automated Clearing House

 

Merchant: Merchant Carrier Accounts Object

In the Merchant Object, the merchantCarrierAccounts array returns the following object.

Name

Data Type

Description

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

The objects in this array display settings that correspond to settings in the merchant’s carrier account. Each object in the array is a name-value pair and contains the following fields:

  • attributeName: The carrier account attribute. This field takes a String.

  • attributeValue: The value of the carrier account attribute. This field takes a String.

registrationDate

Number

The date the merchant’s carrier account was registered 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.

Parcel Object

Name

Data Type

Description

Weight

Weight Object

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

Weight.weight

BigDecimal

Required. The parcel’s weight.

Weight.unitOfMeasurement

String

Required. The unit of measure. Valid values:

For USPS shipments, set this to OZ.

Valid values:

  • OZ: Ounces

  • GM: Grams

The following values are available only for CBDS.

  • LB: Pounds

  • KG: Kilograms

dimension

Dimension Object

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

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

Required for the following shipments:

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

  • PB Standard

  • PB Presort

  • PB Cross-Border (CBDS) when shipping from Canada both internationally and domestically

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

 

Rates Object

Name

Data Type

Description

carrier

String

Required. Carrier name. Valid values are:

  • USPS: PB Expedited or PMOD

  • PBCS: PB Standard

  • PBPRESORT: PB Presort

  • PBI: PB Cross-Border Delivery Service (CBDS)

  • HUB: CBDS Final-Mile Label

  • FEDEX: FedEx

  • UPS: United Parcel Service

serviceId

String

The abbreviated name of the carrier-specific service. For abbreviations, see the Services table on the carrier page of the carrier you are using. This field is required for creating a shipment. The field is optional for rating a parcel.

If you use PB Expedited as the carrier:

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

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

Required if creating a shipment.

parcelType

String

The parcel type. For supported parcel types, see the carrier page for the carrier you are using.

Required for:

  • Creating a shipment

  • Rating a FedEx or UPS parcel

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

specialServices

Array[Special Services Object]

The special services to be applied. For available special services and requirements, see the Special Services table on the carrier page of the carrier you are using.

Important

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

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

inductionPostalCode

String

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

currencyCode

String

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

dimensionalWeight

Object

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

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

dimensionalWeight.
weight

Double

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

dimensionalWeight.
unitOfMeasurement

String

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

  • GM: Grams

  • OZ: Ounces

baseCharge

Double

RESPONSE ONLY. The base service charge payable to the carrier, excluding special service charges.

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

Note: This field does not apply to PB Standard.

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.

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.

Note: This field does not apply to PB Standard.

surcharges

Array[Object]

RESPONSE ONLY. PB Expedited, FedEx, and UPS only. Additional fees or surcharges for the shipment. Each object in the array defines a surcharge and fee.

surcharges.name

String

The type of surcharge. For possible surcharges, see the carrier page of the carrier you are using.

surcharges.fee

Double

The amount of the surcharge.

alternateBaseCharge

Double

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

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

alternateTotalCharge

Double

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

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

deliveryCommitment

Object

RESPONSE ONLY. Time in transit for the shipment. For PB Expedited, see also Pitney Bowes Delivery Guarantee.

Note: This field does not apply to PB Standard.

deliveryCommitment.
minEstimatedNumberOfDays

String

The minimum number of delivery days.

deliveryCommitment.
maxEstimatedNumberOfDays

String

The maximum number of delivery days.

deliveryCommitment.
estimatedDeliveryDateTime

String

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

deliveryCommitment.
guarantee

String

States whether carrier delivery is guaranteed. Possible values:

  • FULL

  • NONE

deliveryCommitment.
additionalDetails

String

These are carrier specific details that may be provided.

destinationZone

See Description

RESPONSE ONLY. PB Expedited, PB Presort, PMOD, & CBDS only. The destination zone used to determine the rate. The zone is based on the origin address and destination address. The origin address can be a hub address.

The data type is:

  • String for PB Expedited, PB Presort, and PMOD

  • Number for CBDS

rateTypeId

String

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

linePrice

BigDecimal

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

totalTaxAmount

BigDecimal

RESPONSE ONLY. CBDS, FedEx, and UPS only. The total tax amount payable to the carrier.

totalDutyAmount

BigDecimal

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

 

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.

If you are shipping to Puerto Rico or an international destination with FedEx or UPS, and if the importer is different from the final recipient, enter the address of the importer here in the toAddress object. For the address of the recipient, use the soldToAddress object. If the importer is the same as the final recipient, the toAddress and soldToAddress must match.

altReturnAddress

Address Object

PB Expedited and CBDS Only. Sets the address for parcel returns. Use this in the following situations:

  • PB Expedited: If you are sending an international shipment and if you have set the NON_DELIVERY_OPTION option to redirect, use this field to specify the address for a parcel return.

  • CBDS: By default, parcel returns are sent to a shipment’s fromAddress. (Parcel returns are sent from the CBDS Hub.) If the fromAddress is the wrong address for your returns, then you must use the altReturnAddress to enter the correct address for returns. Failure to enter the correct address will result in parcels being returned to the wrong address.

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]

Required, except as noted below. Defines the label, manifest, or other shipping document created by the API call. In a response, this array provides the URL or Base64 string for a document and in some cases can contain multiple objects.

This field does not apply to:
- Rate Parcel API.
- Create CBDS Shipment API if the merchant prints the first-mile 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 additional requirements for a carrier, see the Considerations section on the carrier’s Create Shipment page.

shipmentOptions.name

String

The name of the shipment option.

shipmentOptions.value

String

The value of the shipment option.

customs

Object

For shipments that use customs forms, this object contains the customs information.

Required for the following carriers in the following situations:

  • PB Expedited: Required for shipments to international destinations. Conditional for shipments to APO/FPO/DPO, U.S. Territories, and FAS, as explained in this FAQ.

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

customs.customsInfo

Customs Info Object

Customs clearance information for the commercial invoice. When using the Customs Info Object, make sure to include the fields marked Required.

customs.customsItems

Array[Customs Items Object]

Customs clearance information for each commodity. When using the Customs Items Object, make sure to include the fields marked Required.

The maximum number of objects in this array is 30.

domesticShipmentDetails

Domestic Shipment Details Object

CBDS Only. The tracking number and other information about the first-mile leg of the shipment. This does not apply if the Create Shipment API prints the first-mile label.

Required if the merchant prints the first-mile label prior to invoking the Create Shipment API.

soldToAddress

Address Object

FedEx, UPS Only. The final recipient of a the shipment.

Required for shipments from the U.S. to Puerto Rico or international destinations. 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. For PB Expedited Return labels and PB Standard Return labels, set this to RETURN.

Required for rating and creating Expedited Returns, and for creating Standard Returns. Note that you cannot rate Standard Returns.

references

Array[Object]

PB Standard and CBDS Only. The merchant’s reference fields. Each object in the array includes a name-value pair that defines a reference field. See the following, depending on your carrier:

To pass references for carriers other than the above, see How do I Add Reference Fields for My Carrier?

hazmatDetails

Hazmat Details Object

PB Standard Only. If shipping hazardous materials with PB Standard, use this object.

carrierPayments

Array[Shipment: Carrier Payments Object]

FedEx, UPS Only. Indicates that one or more of the shipment costs should be charged to a third-party account.

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: Carrier Payments Object

Name

Data Type

Description

accountNumber

String

The account number with the carrier of the party responsible for the specified charge. The charge is specified in the typeOfCharge field.

countryCode

String

The country code of the party responsible for the charge.

party

String

The role of the party responsible for the charge. Possible values:

  • BILL_RECEIVER

  • BILL_SENDER

  • BILL_THIRD_PARTY

  • BILL_RECEIVER_CONTRACT

postalCode

String

The postal code of the party responsible for the charge.

typeOfCharge

String

The type of charge for which the party will be billed. Possible values:

  • TRANSPORTATION_CHARGES

  • DUTIES_AND_TAXES

  • ALL_CHARGES

 

Special Services Object

Name

Data Type

Description

specialServiceId

String

Required. The abbreviated name of the special service to be applied. For abbreviations, see the Special Services table on the carrier page of the carrier you are using.

Important

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

inputParameters

Array[Object]

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

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

inputParameters.name

String

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

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

inputParameters.value

String

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

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

fee

Double

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

 

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.

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 page for the carrier you are using.

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

For a PB Expedited Returns label, the label’s status. Possible values:

  • Printed: The label has been printed but not used.

  • Charged: The label has been used.

Note: This information also appears in the status field.

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.

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.

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.

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

  • PB Expedited Returns label. Possible values:

    • Printed

    • Charged

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.

clientFacilityId

String

For a PB Standard transaction, this is the ID that was assigned to the merchant’s facility during onboarding with PB Standard.

carrierFacilityId

String

For a PB Standard transaction, this is the ID of the PB Standard facility that was assigned to the merchant during onboarding with PB Standard.

inductionPostalCode

BigDecimal

The postal code where the shipment was tendered to the carrier.

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

tracking

Object

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.

Note: This object is not returned by the Get Archived Reports API.

tracking.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 record tracking status only for the first 30 days after the parcel’s ship date.

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

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.

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.