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 Cross-Border shipment or quote.
Contact A new merchant’s contact information, sent as part of the Sign Up a Merchant API call. Contact information can be different from the merchant’s billing information.
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 PB Cross-Border shipment.
Manifest A document that combines packages into a single form.
Merchant A merchant. Each merchant is uniquely identified by the value of the postalReportingNumber field.
Parcel The physical characteristics of a parcel.
Payment Info A merchant’s payment method.
Pickup The details of a scheduled package pickup.
Rates Information related to the shipment rates.
Shipment A shipment.
Transaction Detailed information associated with a transaction.
User Info Merchant address and other information used when setting up a payment method.

This page also describes the following input options:
 
Manifest Parameters
Used in the Manifest Object.
Shipment Options Used in the Shipment Object.

 

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.

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.

Required for:
cityTown String

The city or town.

Required for:
stateProvince String

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

Required for:
postalCode String

Required. (See exceptions below.) This field contains 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.

Not Required for:
countryCode String Required. Two-character country code from the ISO country list.
company String

The name of the company.

Required for:
name String

The first and last name.

Required for:
phone String

The phone number.

Required for:

  • USPS Priority Mail Express (EM) shipments (i.e., Express Mail), in the fromAddress object
  • USPS SBR labels in the fromAddress object
  • Pickups
email String

The email address.

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

 

Contact Object

Name Data Type Description
email String Required. Email address.
firstName String Required. First name.
lastName String Required. Last name.
company String Required. Company name.
phone String

Required. A valid phone number for the merchant.

For USPS, this must be a valid 10-digit number. The string should contain 10 numeric characters and no additional characters. For example: "8442566444"
addressLines Array[String]

Required. Street address, including the apartment number if applicable.

Note: For USPS, the address cannot be a P.O. Box.
cityTown String Conditional. The city or town. Required if postalCode is absent.
stateProvince String

Conditional. The state or province. For US addresses, use the 2-letter state code.

Required if postalCode is absent; otherwise optional. Note that in some cases where cityTown is a unique name within the country, this can be left out, even if postalCode is absent. But the best practice is to include this field whenever postalCode absent.
postalCode String

Conditional. The postal/ZIP code. For US addresses, use either the 5-digit or 9-digit ZIP code.

Required if you are creating a shipment. Optional if you are rating a package.
countryCode String Required. Two-character country code from the ISO country list.

 

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

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

Required for PB Cross-Border. Set the value to USD.
customsDeclaredValue BigDecimal The value of the item that is going to be declared in customs.
EELPFC
String Conditional. EEI/PFC is the Electronic Export Information and Proof of Filing Citation. Both are required if the item you are shipping internationally is valued over $2,500 USD per Schedule B export codes.
freightCharge BigDecimal RESPONSE ONLY.
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 RESPONSE ONLY.
importerCustomsReference String A reference number used by the importer. For example, a PO number or insured number.
insuredAmount BigDecimal The declared value of the item for insurance purposes expressed in USD.
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 RESPONSE ONLY.
packingCosts BigDecimal RESPONSE ONLY.
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 Conditional. 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.
shippingDocumentType String UPS Only.
termsOfSale String UPS Only.

 

Customs Items Object

The available fields depend on the carrier. Carriers are listed by the carrier name used in the Rates object’s carrier field.

Name
Data Type Applies to these Carriers Description
description String USPS,
PBI,
UPS

Required. A detailed description of the commodity. For PB Cross-Border (PBI), make the description as detailed as possible to facilitate assignment of the correct HS Code.

For the Cross-Border Quotes API, this field allows up to 255 characters. For the Rate Parcel and Create Shipment APIs, the maximum is 50 characters.
quantity Integer USPS,
PBI,
UPS

Required. 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.
unitPrice BigDecimal USPS,
PBI,
UPS		 Required. The price of one item of this type of commodity.
url String PBI Recommended for PBI. 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.
unitWeight Object USPS,
PBI,
UPS		 Conditional. The weight of one item of this type of commodity. This is required for international shipments, except for PB Cross-Border (PBI). This is not required for PB Cross-Border.
      weight Number   “ The weight in the units specified in the unitOfMeasurement field. This field is required by the unitWeight object.
      unitOfMeasurement String   “

The unit of measurement. This field is required by the unitWeight object. If USPS is the carrier, set this to OZ. This field can take the following values:
originCountryCode String USPS,
PBI,
UPS		 The country code of the shipment’s origin country. Use ISO 3166-1 alpha-2 standard values.
hSTariffCode String USPS,
PBI,
UPS

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 use this field for a PB Cross-Border (PBI) operation, you must also enter information in the hSTariffCodeCountry field.
hSTariffCodeCountry String PBI Conditional. The two-character ISO country code for the destination country. This field is required for PB Cross-Border if the hSTariffCode field is used.
itemId String PBI Required for PB Cross-Border (PBI). The merchant’s unique identifier for the commodity. The maximum length is 50 characters.
identifiers Array[Object] PBI Additional identifiers for the item. For example:
      number String   “ The value of the identifier. The maximum length is 50 characters. This field is required by the identifiers array.
      source String   “ The type of identifier, such as MPN, SKU, UPC, ISBN, or ISSN. The maximum length is 10 characters. This field is required by the identifiers array.
condition String PBI

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
manufacturer String PBI The manufacturer of the item. The maximum length is 255 characters.
categories Array[Categories Object] PBI Associated categories. The merchants category tree must have been provided to PB Cross-Border (PBI) in advance. Do not use this array if the category tree has not been provided in advance.
itemDimension Object PBI The dimensions for a single item.
      length BigDecimal   “ The longest dimension. This field is required by the itemDimension object.
      height BigDecimal   “ The second longest dimension. This field is required by the itemDimension object.
      width BigDecimal   “ The shortest dimension. This field is required by the itemDimension object.
      unitOfMeasurement String   “

The unit of measurement. This field is required by the itemDimension object. Valid values are:

  • IN: Inches
  • FT: Feet
  • YD: Yards
  • CM: Centimeters
  • M: Meters
brand String PBI The manufacturer’s brand name for the item. The maximum length is 255 characters.
imageURL Array[String] PBI URLs to images of the commodity.
hazmats Array[String] PBI The identification of a HAZMAT-flagged item. For valid values please see How do I identify a HAZMAT-flagged item?
eccn String PBI The Export Control Classification Number (ECCN) for the commodity. The maximum length is 10 characters.
pricing Object PBI The pricing information for the commodity. If the information is not in the shopping cart, then this information is used.
      price BigDecimal   “ List price of the item.
netCostMethod String UPS  
originStateProvince String UPS  
preferenceCriterion String UPS  
producerAddress Address Object UPS  
producerDetermination String UPS  
producerId String UPS  
quantityUOM String UPS  

 

Documents Object

Name Data Type Description
type String

The type of document. Valid values are:

  • SHIPPING_LABEL
  • 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, Newgistics, 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 API returns a link to the label or manifest.

  • BASE64: The API 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.

    The BASE64 option is available only for shipping labels.
fileFormat String

Conditional. The file format for the document. This field is required if the type field is set to SHIPPING_LABEL.

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

The label’s dots per inch (DPI). This field:

  • Applies only to USPS and Newgistics shipments.
  • Is not required.
  • 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 and other conditions. For the valid values for your API call, please see either USPS Labels or Newgistics Labels:

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

Shipping Labels Only. 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.

Required if creating a shipment.

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 shipment request, this defines additional information to be printed on the 2-inch Doc Tab of a 4X8 label. You can specify information returned by the Create Shipment API as well as custom information. 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 call 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 call, 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 in Create Shipment, 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.

 

Domestic Shipment Details Object

Name Data Type Description
shipperTrackingNumber String Required. The first-mile tracking number, which is the tracking number for the domestic leg of the shipment.
carrier String

Required. The carrier for the domestic leg of the shipment. Valid values are:

  • USPS
  • NEWGISTICS
dcAddress Address Object Required. The origin address for the domestic leg of the shipment. The parcel is shipped from this address to the PB Cross-Border 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 - Valid only in a Create Manifest request
  • PBPresort - Valid only in a Create Manifest request
submissionDate String

Required. The time and date the shipments are to be tendered to the carrier. The time and date must be in UTC/GMT and in one of the following formats:

  • YYYY-MM-DD
  • YYYY-MM-DD HH:mm:ss
  • YYYY-MM-DD HH:mm:ss.SSS
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 Newgistics manifests.
parcelTrackingNumbers Array[String]

Identifies shipments by their tracking numbers. List one or more shipment tracking numbers, separated by commas.

This field does not apply to Newgistics manifests.
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 Newgistics 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.
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 Newgistics manifest.

 

Manifest Parameters

When creating a manifest, you can set the following options in the parameters array.

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

Newgistics Only. The Newgistics Merchant ID provided by Newgistics. If testing in the sandbox environment, set this to NGST.

Required for Newgistics manifest requests.
CARRIER_FACILITY_ID_<#>
where <#> is an integer from 1 to 5.

Newgistics Only. Each instance of this parameter lists a Newgistics Facility ID 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, include multiple instances of this parameter, up to five. Start with CARRIER_FACILITY_ID_1 and increment by 1 up to CARRIER_FACILITY_ID_5.

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.

 

Merchant Object

The merchant object appears only in an API response. The object returns information about a merchant.

Name
Data Type Description
fullName String The merchant’s full name.
email String The merchant’s email address.
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.
deactivatedDate Number

For an inactive merchant, the date the merchant’s account was deactivated, shown as milliseconds since the Unix Epoch. For an active merchant, this field is set to null.

To convert milliseconds since the Epoch to human-readable form:

  1. Round from milliseconds to seconds.
  2. Apply the Unix timestamp conversion algorithm.

Alternatively, use a web site that converts milliseconds since the Epoch, such as https://currentmillis.com.
paymentAccountNumber String The Pitney Bowes customer account number assigned to the merchant.
enterpriseAccount String An enterprise account number that is associated with the merchant.
subscriptionAccount String Any subscription account that the merchant might have.
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.
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 set to null.
parcelProtection String If true, the merchant can choose to request PB Parcel Protection coverage when creating a shipment.
paymentKey String If the merchant uses ACH as the payment method, this returns the ACH payment key. Otherwise this returns the null value.
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 returns the null value.

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

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

  • UPS
  • FEDEX (Coming soon to Sandbox)
    deactivationDate Number If the merchant has removed the carrier account, this is the date the account was removed.
    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 carrier account was registered to be used with Pitney Bowes.
    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.

Merchant’s Carrier Account Attributes

The following attributes and their values are returned for merchants who have registered additional commercial carrier accounts other than Newgistics or PB Presort:

Attribute Name Description
ACCOUNT_NUMBER

The merchant’s account number with the carrier.

Note that this value also appears in the accountNumber field.
KEY UPS Only. The API access key for the UPS account.
METER_NUMBER FedEx Only. The identifier FedEx has assigned for this instance of the account’s registration.
PASSWORD The password Pitney Bowes uses to access to the carrier account on behalf of the merchant. Do not use this password. Instead, use the value returned in the shipperCarrierAccountId field.
USER_ID The username Pitney Bowes uses to access the carrier account on behalf of the merchant. Do not use this username. Instead, use the value returned in the shipperCarrierAccountId field.

 

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 PB Cross-Border carrier service.
  • KG: Kilograms. Available only for PB Cross-Border carrier service.
dimension Object

Recommended. Defines the parcel’s dimensions. Required for the following:

  • USPS PRCLSEL
  • USPS soft packs
  • Newgistics shipments
  • PB Presort shipments

Note: Shippers are encouraged to provide dimensions for all packages, especially for packages with dimensions that exceed 1 cubic foot.

Order of Dimensions: When you set dimensions, set length as the longest dimension, height as the second longest dimension, and width as the shortest dimension. If you assign values differently, the APIs will reassign them accordingly.

For example, if you assign the following values:

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

The APIs will reassign the values as follows:

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

To leave out dimension, which is not recommended, omit the dimension object or send it with an empty payload.
    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 Newgistics 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.

Example currency codes: USD, CAD, EUR

 

Payment Info Object

The paymentInfo object is used in the request body of the Sign Up a Merchant API call and contains the merchant’s payment method.

Name
Data Type Description
paymentType String

Required. The payment type.

  • For PB Line of Credit, do one of the following:
    • Create one one paymentInfo object with this field set to POSTAGE_AND_SUBSCRIPTION.
    • Create two paymentInfo objects: one with this field set to SUBSCRIPTION and the other with this field set to POSTAGE.
  • For Credit Card payment, create two paymentInfo objects, one with this field set to SUBSCRIPTION and the other with this field set to POSTAGE.
paymentMethod String

Required. The payment method. Valid values:

  • PurchasePower: PB Line of Credit
  • CC: Credit card payment
ppPaymentDetails Object

PB Line of Credit Only. The tokenized payment information for a PB Line of Credit.

Required if the paymentMethod field is set to PurchasePower.
    encryptedTIN String The merchant’s encrypted TIN (Taxpayer Identification Number).
ccPaymentDetails Object

Credit Card Only. The credit card information, including the tokenized credit card number. This field is required if the paymentMethod field is set to CC.

All the fields in the ccPaymentDetails object are required fields.
    ccType String

The type of credit card, as specified by one of the following abbreviations:

  • Amex
  • MC
  • Visa
  • Disc
    ccTokenNumber String The tokenized credit card number.
    ccExpirationDate String The month and year the card expires, entered as the two-digit month and four-digit year separated by a backslash. For example: 06/2021
    cccvvNumber String The three- or four-digit Card Verification Value.
    ccAddress Object The address associated with the credit card account.
        addressLines Array[String] Street address or P.O. Box. Include apartment number if applicable. You can specify up to three address lines.
        cityTown String City or town.
        stateProvince String State or province.
        postalCode String Postal or ZIP code.
        countryCode String Two-character country code from the ISO country list.
        firstName String First name as it appears on the credit card.
        lastName String Last name as it appears on the credit card.

 

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 - U.S. Postal Service
  • NEWGISTICS - Newgistics. Create Shipment request only.
  • PBPRESORT - PB Presort. Create Shipment request only.
  • PBI - Cross-Border
  • UPS - United Parcel Service
  • FEDEX (Coming soon to Sandbox)
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.

USPS:

  • 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 UPS parcel

Not applicable to Cross-Border Quotes.
specialServices Array[Object]

The abbreviated names of the special services to be applied. For abbreviations, 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.

Not applicable to Cross-Border Quotes.
    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 carrier’s special services, 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.
inductionPostalCode String

USPS and PB Presort 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 USPS, PB Cross-Border, and UPS Only. Type of currency referenced in the piece price. For example: USD, CAD, EUR
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. USPS, PB Cross-Border, and UPS Only. The base service charge payable to the carrier, excluding special service charges. If your request includes a shipper rate plan, please see this FAQ for information on whether the shipper rate affects this field.
totalCarrierCharge Double RESPONSE ONLY. USPS, PB Cross-Border, and UPS Only. The total amount payable to the carrier, including special service charges. If your request includes a shipper rate plan, please see this FAQ for information on whether the shipper rate affects this field.
surcharges Array[Object]

RESPONSE ONLY. USPS and UPS Only. Additional fees or surcharges for the shipment. Each object in this array has two fields, name and fee. For example:

{
    "name": "oversize",
    "fee": 128.91
}
    name String

The type of surcharge.

If this is set to oversize, then USPS oversize pricing was used to calculate the surcharge. Oversized pricing applies if the parcel’s combined length plus girth falls between 108 and 130 inches.
    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. USPS and UPS Only. Time in transit for the shipment. For USPS, see also: Pitney Bowes Delivery Guarantee
    minEstimatedNumberOfDays String The minimum number of delivery days.
    maxEstimatedNumberOfDays String The maximum number of delivery days.
    estimatedDeliveryDateTime String The estimated delivery date and time.
    guarantee String

States whether carrier delivery is guaranteed. Possible values:

  • FULL
  • NONE
    additionalDetails String These are carrier specific details that may be provided.
destinationZone Number RESPONSE ONLY. USPS Only. Destination Zone based on the fromAddress and toAddress specified.
rateTypeId String

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

This field is returned in the Retry Shipment and Reprint Shipment API calls.
totalTaxAmount BigDecimal RESPONSE ONLY. PB Cross-Border and UPS only. The total tax amount payable to the carrier. Applies only to the PB Cross-Border Carrier Service.
totalDutyAmount BigDecimal RESPONSE ONLY. PB Cross-Border only. The total duty amount payable to the carrier. Applies only to the PB Cross-Border Carrier Service.

 

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.

Note for UPS: If you are shipping with United Parcel Service (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

Applies only to the following:

  • 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.
  • PB Cross-Border: For a Create Shipment request, this is the address used to return a parcel from the Pitney Bowes 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 shipment document. Applies as follows:

  • Required for Create Shipment requests except as noted in the next bullet.
  • Does not apply to a Cross-Border Create Shipment request.
  • Does not apply to Rate Parcel requests.
shipmentOptions Array[Object] Conditional. Each object in this array defines a shipment option. Required for Create Shipment requests. Does not apply to Rate Parcel requests. All Create Shipment requests require the SHIPPER_ID option. Please see the Things to Consider section on the carrier’s Create Shipment page for any additional requirements.
        name String The name of the shipment option. The shipmentOptions array requires this field.
        value String The value of the shipment option. The shipmentOptions array requires this field.
customs Object

Conditional. For shipments that use customs forms, this object contains the customs information. This field is required for:

  • USPS shipments to international destinations and to APO/FPO/DPO, Territories/Possessions, and FAS
  • PB Cross-Border
  • UPS 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 PB Cross-Border Only. Required in Create Shipment requests; does not apply to Rate Parcel requests. Contains information about the domestic leg of the PB Cross-Border shipment.
soldToAddress Address Object

UPS Only. The final recipient of a United Parcel Service 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 USPS Return Labels Only. Required for USPS Return Labels. If you are creating a Pure Post Return label or Scan-Based Return label, include this field and set the value to RETURN.
references Array[Object]

Applies only to the following:

  • PB Cross-Border: Required in a Create Shipment request; does not apply to a Rate Parcel request. Contains the buyer order ID. The array takes an object with two String elements. Set name to ORDER_NUMBER, and set value to the order ID:

    {
    "name": "ORDER_NUMBER",
    "value": "<order_ID>"
}

  • Newgistics: Optional. This array maps client-generated identifiers to fields in the Newgistics package record. The information in this array does not appear on the shipping label. The array takes up to three objects, and each object maps an identifier to a specific Newgistics field. An object’s sequence in the array determines which Newgistics field the object maps to. The first object in the array maps to the Newgistics “ReferenceNumber” field; the second to the “AddlRef1” field; and the third to the “AddlRef2” field.

    Use the syntax shown below. Enter the names in the order shown. If you enter different names, the system will change them to the names below. In the value fields, enter the client-generated identifiers. The values must be strings of no more than 50 characters each. For additional information on using references, merchants can contact their Newgistics representatives.

    {
    "name": "ReferenceNumber",
    "value": "<client identifier 1>"
}, {
    "name": "AddlRef1",
    "value": "<client identifier 2>"
}, {
    "name": "AddlRef2",
    "value": "<client identifier 3>"
}
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

When creating a shipment, you can set the following options in the shipmentOptions array. The SHIPPER_ID is required.

Name Description
Applies to the following carriers
ADD_TO_MANIFEST

Set this value to true in order to make this shipment eligible to be included in the end-of-day manifest.

For Newgistics and USPS PMOD labels, the system always sets this to true, no matter how the option is set in the API call.

The following USPS shipments cannot be added to a SCAN form:

  • FCM flats
  • FCM letters
  • Scan-Based Returns
 USPS,
Newgistics (always true),
PB Presort,
PB Cross-Border,
PMOD (always true)
CARRIER_FACILITY_ID
  • If creating a Newgistics shipment, set this to the Newgistics Facility ID provided by Newgistics. If testing in sandbox, set this to 1585.
  • If creating a PB Cross-Border shipment, use this field if the shipper does not use an integrated first-mile solution. Set this to the Consolidation Center ID listed in Cross-Border Consolidation Centers.
 Newgistics,
PB Cross-Border
CLIENT_FACILITY_ID
  • If creating a Newgistics shipment, set this to the Client Facility ID provided by Newgistics. If testing in sandbox, set this to 0093.
  • If creating a PB Cross-Border shipment, set this to the distribution center ID of the shipper.
 Newgistics,
PB Cross-Border
CLIENT_ID Cross-Border Quotes Only. If the merchant uses Newgistics, set this to the Newgistics Merchant ID. See Newgistics IDs. PB Cross-Border
FUTURE_SHIPMENT_DATE

  • In a request: Use this field if the shipment label is to be tendered at a future date. Specify this value in UTC/GMT using one of the following formats:

    • YYYY-MM-DD
    • YYYY-MM-DD HH:MM:SS

    USPS only: USPS limits how long you can extend the date. You can extend the ship date up to 7 days.

  • In response: This lists the shipment date in UTC/GMT. This lists the shipment date even if the date is not a future date but is the current day.

 USPS,
Newgistics,
PB Cross-Border,
FedEx (Coming soon to Sandbox)
HIDE_TOTAL_CARRIER_CHARGE

Set the value to true in order to hide the carrier shipping charge on the label. Please note, the carrier shipping charge will still appear on the receipt. This field applies to both domestic and international shipments.

Note: When shipping to Brazil, set this option to false. Per Conditions for Brazil in the International Mail Manual, shipments to Brazil that do not indicate the applicable postage and fees on PS Form 2976-A can hinder the customs clearance process and cause delays in clearing the items.

 USPS,
PB Presort,
PB Cross-Border
IS_RECTANGULAR

This is true by default.

For a Newgistics shipment, if you set IS_RECTANGULAR to false, then you must set a value for irregularParcelGirth in the Parcel Object.

 Newgistics
MINIMAL_ADDRESS_VALIDATION

Domestic Addresses Only. When this is set to true, address validation will not make changes to the delivery line (street address). Address validation will make corrections only to the city, state, and postal code. The APIs will still, however, evaluate the entire address against current USPS address data to ensure the address is not marked as undeliverable.

For details, see What is minimal address validation?

By default, this option is false.

 USPS,
Newgistics,
PB Presort,
PB Cross-Border,
FedEx (Coming soon to Sandbox),
UPS
NON_DELIVERY_OPTION

Provides instructions if a parcel cannot be delivered for the following labels:

  • USPS international labels. Valid values are:
    • return: Return the parcel to the shipment’s fromAddress.
    • redirect: Return the parcel to the shipment’s altReturnAddress.
    • abandon: Don’t return the parcel.
  • Newgistics labels. Valid values are:
    • AddressServiceRequested
    • AddressServiceRequestedBPRS
    • ReturnServiceRequested
    • ReturnServiceRequestedBPRS
    • ChangeServiceRequested
    • ForwardingServiceRequested
    • ElectronicServiceRequested
  • PB Presort flats. Valid value is:
    • ElectronicServiceRequested. This prints the Electronic Service Requested endorsement on the PB Presort label.
 USPS,
Newgistics,
PB Presort,
PB Cross-Border
PERMIT_NUMBER The merchant’s permit number for flats. You must include the merchant’s permit number in the request when shipping letters and flats through PB Presort. PB Presort
PRINT_CUSTOM_MESSAGE_1

Domestic Labels Only. Prints a custom message along the side of the address portion of the label.

For USPS and PB Presort PKG, you can enter up to 50 characters.

For PB Presort LGENV, you can enter up to 25 characters.

Note: This option is not supported for 6X4 labels with IMb barcodes.

 USPS,
PB Presort PKG,
PB Presort LGENV,
FedEx (Coming soon to Sandbox)
PRINT_CUSTOM_MESSAGE_2

Use of this field depends on the carrier:

  • USPS, Newgistics, PB Presort: Domestic Labels Only. Prints a user-defined custom message on the label of up to 50 characters. On a 4X6 USPS domestic label, this prints a custom message of up to 102 characters (three lines of 34 characters each).

    For USPS and PB Presort, the custom message appears on the bottom of the label. For Newgistics, the message is printed at the bottom right of the address section of the label.

    Note: This option is not supported for 6X4 labels with IMb barcodes.

  • PB Cross-Border: Prints the end-to-end tracking number assigned by PB Cross-Border.

 USPS,
Newgistics,
PB Presort (PKG parcel type only),
PB Cross-Border
PRINT_IMBREADABLE_BARCODE Set this option to True to print human-readable tracking information on a PB Presort label that uses STANDARD mail with LGENV. By default, this option is set to False. PB Presort
PRINTER_MODEL

Uses ASCII instead of Unicode to generate labels. This option is intended for older ZPL printers that do not support Unicode. By default, the PB Shipping APIs generate labels using the Unicode character set, which supports international characters.

Important: If you request ASCII, international characters might not print properly. Consider contacting your Zebra printer provider to update your printer’s firmware to a version that supports Unicode.

To request ASCII, set this option to ZP500 (which simply means generate with ASCII and does not mean your printer must be a ZP500):

{
    "name": "PRINTER_MODEL",
    "value": "ZP500"
}
USPS,
Newgistics,
PB Presort,
PB Cross-Border,
PMOD
SHIPPER_ID The Shipper ID of the merchant on whose behalf the label is being printed. The merchant’s Shipper ID is found in the postalReportingNumber field in the Merchant Object. USPS,
Newgistics,
PB Presort,
PB Cross-Border,
FedEx (Coming soon to Sandbox),
UPS
SHIPPING_LABEL_RECEIPT

DOC_8X11 Labels Only. Prints a receipt for the shipping label. Valid values are:

  • NO_OPTIONS (default)
  • RECEIPT_ONLY
  • RECEIPT_WITH_INSTRUCTIONS
  • INSTRUCTIONS_ONLY
 USPS,
PB Presort
SHIPPING_LABEL_SENDER_SIGNATURE Adds the sender’s signature and the date on CN 22 and CP 72 shipping labels. Enter the signature as a String. The sender’s signature date is automatically populated. USPS,
PB Presort

 

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, specified using ISO 8601.
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 used to report data at this time. This field always returns the null value.
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 this field is 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.
printStatus String

The status of a USPS SBR label:

  • SBRPrinted: The SBR label has been printed but has not been scanned in to the USPS mailstream.
  • SBRCharged: The SBR label has been scanned into the USPS mailstream.
  • NULL: The label is a prepaid outbound label (i.e., not an SBR label).
shipmentId String The unique identifier for the shipment generated when the shipment was created.
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.
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.
adjustmentReason String

APV Only. The reason for an APV adjustment, based on information received from USPS.

For an APV adjustment, possible values are:

  • Weight
  • Dimension
  • Package
  • Zone
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.
meterNumber String Internal identification number for the postage meter that was used.
dimensionalWeightOz BigDecimal

API v4.0 Only. Returned only if the shipDetails query parameter is set to 1.

This field contains the dimensional weight, if applicable.
valueOfGoods BigDecimal

API v4.0 Only. Returned only if the shipDetails query parameter is set to 1.

This field contains the value provided in the parcel.valueOfGoods field in the Create Shipment request, if applicable.
specialServices Array[Object]

API v4.0 Only. Returned only if the shipDetails query parameter is set to 1.

This array contains the shipment’s special services, including the fee paid for each service.
status String

API v4.0 Only. For the following types of transactions, this field shows the transaction status:

  • 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
  • Return label (Sandbox only). Possible values:
    • Printed
    • Charged
description String

API v4.0 Only. 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.
customMessage1 String

API v4.0 Only. Returned only if the shipDetails query parameter is set to 1.

This fields contains the message specified in the PRINT_CUSTOM_MESSAGE_1 shipment option in the Create Shipment request.
customMessage2 String

API v4.0 Only. Returned only if the shipDetails query parameter is set to 1.

This fields contains the message specified in the PRINT_CUSTOM_MESSAGE_2 shipment option in the Create Shipment request.

 

User Info Object

The userInfo object contains merchant information used when setting up a payment method.

Name
Data Type Description
email String Required. Email address.
phone String Required. Phone number.
firstName String First name
lastName String Last name
company String Required. Company name.
address Object Required. The merchant’s full address.
    addressLines Array[String] Required. Street address or P.O. Box. For a street address, include the apartment number if applicable.
    city String Required. City or town.
    state String Required. State or province. For US addresses, use the 2-letter state code.
    postalCode String Required. Postal/ZIP code. For US addresses, use either the 5-digit or 9-digit ZIP code.
    countryCode String Required. Two-character country code from the ISO country list.