Core Resource Objects

On this page:

This page describes the following JSON objects used by the PB Shipping APIs:

address Full address. Includes address validation status when minimum validation is disabled.
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 Customs-related information, especially for international shipments. Contains commodity and customs-clearance information.
documents The shipment documents, including the label.
manifest A manifest that combines trackable 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.
paymentInfo 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.
userInfo 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

Name Data Type Description
addressLines Array[String]

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

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

cityTown String

The city or town name.

Required in the following cases:

stateProvince String

State or province name. For US address, use the 2-letter state code.

Required in the following cases:

postalCode String Required. Postal/ZIP code. For US addresses, either the 5-digit or 9-digit ZIP code.
countryCode String Required. Two-character country code from the ISO country list.
company String

Name of the company.

Required in the following cases:

name String

First and last name.

Required in the following cases:

phone String

Phone number.

Required in the following cases:

  • Priority Mail Express (EM) shipments (a.k.a. Express Mail shipments) require this field in the fromAddress object.
  • Scheduling a pickup.
  • Creating an SBR label requires this field in the fromAddress object.
email String

Email address.

Required in the fromAddress object if creating an SBR label.

residential Boolean Indicates whether this is a residential address. It is recommended that this parameter be passed in as the address verification process is more accurate with it.
deliveryPoint String The 2-digit delivery point, when available.
carrierRoute String The last four characters of the USPS 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.

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

 

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

City or town.

Required if postalCode is absent.

stateProvince String

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

Required if postalCode is absent. 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

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

Required if cityTown and stateProvince are absent.

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 Object

Name Data Type Description
customsInfo Object Customs clearance information that is used to fill out a commercial invoice
    reasonForExport String

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

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

Note: In accordance with January 2018 USPS changes, First-Class Mail International (FCMI) shipments can contain only documents, not goods. If using FCMI, you must set this field to DOCUMENTS. Goods that were formerly shipped via FCMI are eligible to be shipped via First-Class Package International Service (FCPIS) and other services.

    reasonForExportExplanation String

The reason the commodity is being exported.

Required if the reasonForExport field is set to OTHER.

    comments String Free form comments regarding the exported shipment entered by the shipper.
    invoiceNumber String The commercial invoice number assigned by the exported.
    importerCustomsReference String A reference number used by the imported. For example, a PO number or insured number.
    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.
    insuredAmount BigDecimal The declared value of the item for insurance purposes expressed in USD.
    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.
    EELPFC
String 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.
    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.
    customsDeclaredValue BigDecimal The value of the item that is going to be declared in customs.
    currencyCode String Type of currency referenced in the piece price. Use three uppercase letters, per ISO 4217. For example: USD, CAD, EUR.
    licenseNumber String The export license number associated with the commodity.
    certificateNumber String The certificate number associated with the commodity.
customsItems Array[Object]

The information about each commodity in the shipment, used for customs clearance.

Maximum: The maximum number of objects in this array is 30.

    description String The description of the commodity.
    quantity Integer

The total number of items of this type of commodity. USPS limits the number of items of one commodity to 9999.

Maximum: 9999

    unitPrice BigDecimal The price of one item of this type of commodity.
    unitWeight Object The weight and UOM of one item of this type of commodity.
            weight Number The weight of one item.
            unitOfMeasurement String The unit of measurement.
    hSTariffCode String The Harmonized Tariff associated with the commodity.
    originCountryCode
String The country code of the shipment’s origin. Use ISO 3166-1 alpha-2 standard values.

 

Documents Object

Name Data Type Description
type String

The type of document. Required if creating a shipment.

Valid values are:

  • SHIPPING_LABEL
  • MANIFEST
size String

Shipping Labels Only. The size of a shipping label. Required if creating a shipment. The value specified is the recommended size of the label. The actual size depends on the carrier.

Valid values are:

  • DOC_4X5 (Newgistics labels only)
  • DOC_4X6
  • DOC_4X8
  • DOC_6X4
  • DOC_8X11

For the combinations of fileFormat and contentType that are available for each label size, see Supported Label Sizes & Formats.

contentType String

How the API returns the document. Required if creating a shipment.

Valid 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. This option is available only for shipping labels.

For the combinations of fileFormat and size that are available for each content type, see Supported Label Sizes & Formats.

fileFormat String

The file format for the document. Required if creating a shipment.

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

For the combinations of contentType and size that are available for each file format, see Supported Label Sizes & Formats.

resolution String

USPS Shipping Labels Only.

If fileFormat is set to PNG for a USPS shipping label, you can specify the DPI (Dots Per Inch). By default, a PNG label uses 300 DPI. You can specify the following:

  • DPI_203: The label uses 203 DPI.
  • DPI_300: The label uses 300 DPI.

Note: This field does not apply to 4X8 labels, COD labels, and PMOD labels.

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

 

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 (applicable only if creating a manifest)
  • PBPresort (applicable only if creating a manifest)
submissionDate String

Required. The date the shipments are tendered to the carrier. The time must be in GMT/UTC 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 Required. The shipment origin address.
inductionPostalCode String

Postal code where the shipments are tendered to the carrier.

Note: Not applicable to Newgistics manifests.

parcelTrackingNumbers Array[String]

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

Note: Not applicable to Newgistics manifests.

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.
        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. The manifest tracking number.
documents Array[documents object]

Response Only. The manifest.

Note: 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. 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 the Newgistics Facility ID of shipments to be closed out.

To close out shipments associated with multiple facilities, repeat this parameter for each facility, starting with CARRIER_FACILITY_ID_1 and incrementing by 1 up to CARRIER_FACILITY_ID_5. Set each parameter’s value to a facility ID.

Important: To close out shipments associated with more than 5 facility IDs, you must issue the API call again.

If you are testing in the sandbox environment and include this parameter, include just one instance of the parameter and set its value to 1585.

 

Merchant Object

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

The date the merchant’s account was deactivated, if applicable, shown as milliseconds since the Unix Epoch. A deactivated merchant can no longer print labels. For an active merchant, the field is set to null.

To convert the value to human-readable form, round from milliseconds to seconds and then 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 If you change a merchant’s status from ACTIVE to INACTIVE, you must give a reason for the change. The reason is recorded here. For an active merchant, the field is set to null.
parcelProtection String If true, the merchant can choose to insure a parcel with PB Parcel Protection when creating a shipment.
paymentMethod String

This is returned only for the Authorize Merchant API call. This field indicates the payment method for the merchant’s PB Postage Account. Possible values are:

 

Parcel Object

Name Data Type Description
dimension Object

The parcel’s dimensions. Required for Newgistics; otherwise optional.

The PB Shipping APIs configure 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 PB Shipping APIs will reassign the values as follows:

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

Soft Packs: For soft packs, the maximum total of length plus height cannot exceed 36 inches. The smallest dimension, or width, cannot exceed 2 inches. The measurement must be taken prior to placing items in the envelope.

    length BigDecimal The longest dimension. The dimension object requires this field.
    height BigDecimal The second longest dimension. The dimension object requires this field. Height helps determine a parcel’s girth.
    width BigDecimal

The smallest dimension. The dimension object requires this field. 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 This is either CM for centimeters or IN or inches. The dimension object requires this field.
    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.

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: either GM for Grams or OZ for Ounces.
valueOfGoods BigDecimal

Use of this field depends on whether the merchant is enabled for PB Parcel Protection.

  • Merchant Is Enabled for Parcel Protection: Entering a value in this field purchases PB Parcel Protection. Enter the shipment value in the units specified in the currencyCode field. The shipment must be a domestic shipment.

    Important: Entering a value in this field shows that the merchant intends to buy PB Parcel Protection. This field is not used for insurance values other than PB Parcel Protection.

  • Merchant Is Not Enabled for Parcel Protection: If you want to notate the value of parcel without using a special service, you can define the value in this field.

Important: The valueOfGoods value is independent of the insured, COD, or customs value. If you add insurance or COD as a special service, you still must define the associated INPUT_VALUE in the rates.specialServices array. If you create an international shipment, you still must declare the customs value in the customsInfo.customsDeclaredValue field.

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 for a particular service. For credit card payment, you must create separate paymentInfo objects for subscription and postage payments.

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

  • PurchasePower: PB Line of Credit
  • CC: Credit card payment
ppPaymentDetails Object PB Line of Credit Only. The merchant’s encrypted TIN and encrypted BPN. The object includes an encrypted BPN only if the merchant already has a PB Line of Credit account.
    encryptedTIN String The merchant’s encrypted TIN (Taxpayer Identification Number).
    encryptedBPN String The merchant’s encrypted BPN (Business Partner Number). This field applies only if the merchant already has a PB Line of Credit account.
ccPaymentDetails Object

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

All 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 for all the parcels for this service type.
            weight Number, up to 2 decimal places Required. The total weight for all the parcels for this service type.
            unitOfMeasurement String Required. The unit of measurement.
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

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. Possible values are:

  • USPS
  • NEWGISTICS
  • PBPRESORT

Note: For the Rates API call, not all values apply.

serviceId String

The ID for the carrier service.

Required if you are creating a shipment. Optional if you are rating a package.

To check which special services and parcel types can be used with the service, see Supported Services & Parcel Types.

To determine any additional restrictions on a service, use the Carrier Rules API. See also the USPS Domestic Mail Manual.

Note: The PB Shipping APIs require that all 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.

parcelType String

The carrier parcel type.

Required if you are creating a shipment; optional if you are rating a package.

specialServices Array[Object]

The special services to be applied.

IMPORTANT: Including a special service in this array means you intend to apply the special service.

    specialServiceId String

The abbreviated name of the special service to apply.

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.

To view available parameters and whether parameters are required, issue the Carrier Rules API and locate the special service for the given combination of service and parcel type. The special service’s inputParameterRules array lists the parameter rules. To view how the rules map to this field, see How do I know the input parameters for a special service?.

PMOD: If specialServiceId is set to PMOD_OPTIONS, the inputParameters array must contain each option listed in PMOD Options.

            name String The name of the input parameter. This maps to the inputParameterRules.name field in the Carrier Rules API.
            value String The value of the parameter. 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

Postal code where the shipment is tendered to the carrier. Postal code of Shipment fromAddress is used in absence of this field.

When an inductionPostalCode is present, this postal code is used instead of the postal code in the shipment’s fromAddress when calculating rates and when determining if the shipment can be added to a manifest.

Note: Not applicable to Newgistics or PB Presort.

dimensionalWeight Object

Response 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 balloon or oversize pricing, as explained in the surcharges field below.

    weight Double The calculated DIM weight. For information on how USPS calculates DIM weight, see https://www.usps.com/dimensionalweight/.
    unitOfMeasurement String

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

  • GM: Grams
  • OZ: Ounces
baseCharge Double

Response Only. The base service charge payable to the carrier, excluding special service charges. If your request includes a shipper rate plan, please see this FAQ for information on whether the shipper rate affects this field.

Note: This field is not applicable to Newgistics or PB Presort.

totalCarrierCharge Double

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

Note: This field is not applicable to Newgistics or PB Presort.

surcharges Array[Object] Response Only. A fee charged if balloon pricing or oversized pricing applies.
    name String

The type of pricing used to calculate the surcharge. Possible values are:

  • balloon: The balloon price applies if all the following are true:
    • The parcel uses Priority Mail (Zones 1-4) or Parcel Select (all zones).
    • The parcel weighs less than 20 pounds.
    • The parcel’s combined length plus girth falls between 84 and 108 inches.
  • oversize: The oversized price 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. Applies only if your request includes a shipper rate plan and if the shipper does not have an NSA.

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

Note: This field is not applicable to Newgistics or PB Presort.

alternateTotalCharge Double

Response Only. Applies only if your request includes a shipper rate plan and if the shipper does not have an NSA.

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

Note: This field is not applicable to Newgistics or PB Presort.

deliveryCommitment Object

Response Only. Time in transit for the shipment.

See also: Pitney Bowes Complete Delivery

Note: Not applicable to Newgistics or PB Presort.

    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 the carrier deliver is guaranteed.
    additionalDetails String These are carrier specific details that may be provided.
currencyCode String

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

Note: Not applicable to Newgistics or PB Presort.

destinationZone
Number

Response Only. Destination Zone based on the fromAddress and toAddress specified.

Note: Not applicable to Newgistics or PB Presort.

 

Shipment Object

Name Data Type Description
fromAddress address object

Required. Origin address.

If you want a different address to appear on the label, see How do I print a return address that is different from the origin address?

toAddress address object Required. Destination address.
altReturnAddress address object International Shipments Only. If you are sending an international shipment and if you have set the NON_DELIVERY_OPTION shipment option to redirect, then enter the address that a returned parcel should go to.
parcel parcel object Required. Contains physical characteristics of the parcel.
rates Array[rates object]

Required. Specifies carrier, service, parcel type, and other information. In a response, this field specifies the service charges.

Important: In a request, the rates array can contain only one rates object.

documents Array[documents object] A list of shipment documents pertaining to a shipment, including the label. This field does not apply to Rate a Package requests.
shipmentOptions Array[Object]

Each object in this array defines a shipment option. The available options depend on the carrier, origin country, and destination country.

Required if you are creating a shipment. For shipments the array must contain the SHIPPER_ID option. Other requirements might also apply, depending on the type of shipment.

        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 customs object

Applies only to these shipments:

  • International
  • APO/FPO/DPO
  • Territories/Possessions
  • FAS

This field contains customs information.

shipmentType String SBR Labels Only. If you are creating a Scan-Based Return (SBR) label, include this field and set the value to RETURN.
references Array[Object]

Newgistics Only. 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 PMOD and Newgistics labels, the system always sets this to true, no matter how the option is set in the API call.

USPS,
Newgistics (always true),
PB Presort,
PMOD (always true)
CARRIER_FACILITY_ID Enter the Newgistics Facility ID in this field. If testing in sandbox, set this to 1585. Newgistics
CLIENT_FACILITY_ID Enter the Client Facility ID in this field. If testing in sandbox, set this to 0093. Newgistics
FUTURE_SHIPMENT_DATE

This field can be used if the shipment label is to be tendered at a future date. USPS allows you to extend the shipment date up to 7 days. Specify this value in UTC (Coordinated Universal Time) using one of the following formats:

  • YYYY-MM-DD
  • YYYY-MM-DD HH:MM:SS
USPS
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
IS_RECTANGULAR

This is true by default.

For a Newgistics shipment, if IS_RECTANGULAR is false, then you must set a value for irregularParcelGirth in the parcel object.

Newgistics
MINIMAL_ADDRESS_VALIDATION

Domestic Addresses Only. If this is set to true, and if address validation cannot confirm the delivery line, Pitney Bowes allows address validation to confirm only the city, state, and postal code.

Address validation still checks for completeness and will still return an error if the address is marked “Undeliverable” by USPS.

USPS, Newgistics, PB Presort
NON_DELIVERY_OPTION

This field applies to international labels and to Newgistics labels. This field provides instructions if a parcel cannot be delivered.

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

For Newgistics labels, valid values are:

  • AddressServiceRequested
  • AddressServiceRequestedBPRS
  • ReturnServiceRequested
  • ReturnServiceRequestedBPRS
  • ChangeServiceRequested
  • ForwardingServiceRequested
  • ElectronicServiceRequested
USPS, Newgistics
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. You can enter up to 50 characters. USPS, PB Presort
PRINT_CUSTOM_MESSAGE_2

Domestic Labels Only. Prints a 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).

The location of the message depends on the carrier:

  • USPS and PB Presort: The message is printed on the bottom of the label.
  • Newgistics: The message is printed at the bottom right of the address section of the label.
USPS, Newgistics, 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, PMOD
SHIPPER_BASE_CHARGE (Deprecated) Deprecated. For returned charges, please see Rates Object.  
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
SHIPPER_TOTAL_CHARGE (Deprecated) Deprecated. For returned charges, please see Rates Object.  
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 ISO 8601 date format Date and time of of the transaction.
transactionType String

Type of transaction. Valid values:

  • POSTAGE FUND: The funding of your postage account.
  • POSTAGE PRINT: The printing of a label.
  • POSTAGE REFUND: A refund request or the resolution of a refund request.
  • APV-POSTAGE OVERPAID: An APV adjustment for an overpayment.
  • APV-POSTAGE UNDERPAID: An APV adjustment for an underpayment.
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.
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.
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.
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 Package type. 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 an 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 pre-paid 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.
  • Auto Refund Processor: The transaction is an auto refund.
  • PB Claims: The request is part of the Holiday Guarantee program.
adjustmentReason String

APV Adjustments Only. The reason for an APV adjustment based on the new information received from USPS. Possible reasons are:

  • Weight
  • Dimension
  • Package
  • Zone
  • Duplicate
externalId String

Applies only to the following:

  • APV Adjustments: The unique identifier that USPS assigned to the APV adjustment. If you want to appeal the adjustment, you must send this identifier to USPS. For more information, see How do I dispute an adjustment?.
  • Holiday Guarantee Refunds: The claim number assigned by the the Holiday Guarantee program.

 

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.