Newgistics

Overview

The PB Shipping APIs provide integration to Newgistics® domestic shipping services. Newgistics labels are post-paid labels. Postage is not charged at the time of print.

This page describes how to onboard a merchant and lists supported operations, services, parcel types, and label sizes.

Onboard a Merchant to use Newgistics

  1. Contact Newgistics to set up the merchant at one or more Newgistics hubs. Newgistics will provide the merchant with the following Newgistics IDs, which are required when creating Newgistics shipments and manifests:

    • Client Facility ID
    • Newgistics Facility ID
    • Newgistics Merchant ID

    See Newgistics IDs below for a description of each ID.

  2. If you have not already done so, enroll the merchant within your PB developer account using one of the Merchant Enrollment Models. Pitney Bowes assigns the merchant a PB Shipper ID.

  3. Contact PB Support to enable the merchant to use Newgistics. Send an email to ShippingAPISupport@pb.com and provide the merchant’s Newgistics IDs and PB Shipper ID.

Newgistics IDs

When a merchant is set up at a Newgistics hub, the Newgistics representative provides the merchant with three types of IDs, as listed in the table below. Use the IDs when creating Newgistics shipments and when creating Newgistics manifests to electronically close out the day.

To test Newgistics shipments and manifests in the sandbox environment, use the ID values listed in the Sandbox Value column.

ID
Description API Field Sandbox Value
Client Facility ID The merchant location. A merchant can have multiple client facility IDs. CLIENT_FACILITY_ID When testing in the sandbox environment, set this to 0093.
Newgistics Facility ID The Newgistics facility assigned to the merchant. A merchant can be assigned multiple Newgistics facilities. CARRIER_FACILITY_ID When testing in the sandbox environment, set this to 1585.
Newgistics Merchant ID The unique ID assigned by Newgistics to a merchant. CLIENT_ID When testing in the sandbox environment, set this to NGST.

Shipping Operations

The following shipping operations can be used with Newgistics.

Operation
Method Endpoint

Validate Address

POST

/v1/addresses/verify
 

Suggest Addresses

POST

/v1/addresses/verify-suggest
 

Create Newgistics Label

POST

/v1/shipments
 

Reprint Label

GET

/v1/shipments/{shipmentId}?carrier={carrier}
 

Retry Label

GET

/v1/shipments?originalTransactionId={transaction_id}&carrier={carrier}
 

Void Label

DELETE

/v1/shipments/{shipmentId}
 

Create a Newgistics Manifest (Closeout)

POST

/v1/manifests
 

Get Tracking Information

GET

/v1/tracking/{trackingNumber}?packageIdentifierType=TrackingNumber&carrier=NEWGISTICS
 

Asia-Pacific (APAC) Services

For requests that originate in the Asia-Pacific Region, Pitney Bowes provides regional services to optimize performance. The following Newgistics operations can use the APAC services:

The following are the base URLs for the APAC services:

  • Sandbox: https://apac-sandbox.shippingapi.pitneybowes.com/shippingservices/
  • Production: https://apac.shippingapi.pitneybowes.com/shippingservices/

The full APAC URIs for each operation, including required parameters, are listed in the documentation for the operation. If you use an APAC URI to create a shipment, you must also use an APAC URI should you manifest or void the shipment. When creating a shipment, use these label settings.

Services

The following are the supported services for Newgistics.

ID
Service
BPM Bound Printed Matter
PRCLSEL Parcel Select
PSLW Parcel Select Lightweight
FCM First-Class Mail
PM Priority Mail

Special Services

The following are the supported special services for Newgistics.

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

ID Special Service
Input Parameters (inputParameters)
DelCon Delivery Confirmation

Input parameters are not required for DelCon. To use DelCon, add the following to the rates.specialServices array:

{ "specialServiceId": "DelCon" }
Sig Signature Confirmation

Input parameters are not required for Sig. To use Sig, add the following to the rates.specialServices array:

{ "specialServiceId": "Sig" }
NOTIFICATIONS

Subscribe to provisioned transit triggers.

The merchant must be configured for Newgistics transit triggers to use this special service.

To set input parameters, see the Newgistics Transit Triggers section on the Create a Newgistics Shipment page.

Parcels

The following parcel type is supported for Newgistics.

ID Parcel Type Services Supporting the Parcel Type
PKG Package BPM, PRCLSEL, PSLW, FCM, PM

Labels

Label settings depend on whether your API call uses the default services or the APAC services:

Label Settings

Please read the following considerations before creating a Newgistics shipment. If you use the APAC services, please see these settings instead.

  • The label size, as specified in the documents.size field, uses an upper-case X. Using a lower-case x will result in an error.
  • If you choose to retrieve the label through a URL, the URL is available for 24 hours after the shipment is created.
  • By default, the APIs print ZPL2 labels using the Unicode character set. If you have an older printer that does not support Unicode, see this Troubleshooting topic.
  • Advise shippers on correct label placement. See What is the correct placement for a shipping label?

The table below describes options set in the Documents Object:

Label Size
(size)
File Format
(fileFormat)
Content Type
(contentType)
DPI
(resolution)
DOC_4X4 PDF
PNG
ZPL2 [1]
URL
BASE64
BASE64
DPI_203
DPI_203
• DPI_203 (default)
• DPI_300
DOC_4X5 PDF
PNG
ZPL2 [1]
URL
BASE64
BASE64
DPI_203
DPI_203
• DPI_203 (default)
• DPI_300
DOC_4X6 PDF
PNG
ZPL2 [1]
URL
BASE64
BASE64
DPI_203
DPI_203
• DPI_203 (default)
• DPI_300
[1](1, 2, 3) If you have an older printer that does not support Unicode, see this topic.

Label Settings for APAC Services

For shipments created using the APAC services, the following considerations apply:

  • The label size, as specified in the documents.size field, uses an upper-case X. Using a lower-case x will result in an error.
  • If you set the file format to PDF, you must set contentType to BASE64. The label can be returned only as a Base64-encoded string. It cannot be returned as a URL.
  • If you set the file format to ZPL2 and the content type to BASE64, the label is returned as raw ZPL, not as a Base64-encoded string.
  • By default, the APIs print ZPL2 labels using the Unicode character set. If you have an older printer that does not support Unicode, see this Troubleshooting topic.
  • Advise shippers on correct label placement. Please see What is the correct placement for a shipping label?

The table below describes the options for labels printed with the APAC URIs. Set label options in the Documents Object:

Labels Printed with APAC URIs
Label Size
(size)
File Format
(fileFormat)
Content Type
(contentType)
DPI
(resolution)
DOC_4X4 PDF
PNG
ZPL2 [2]
BASE64
BASE64
BASE64 [3]
DPI_203
DPI_203
• DPI_203 (default)
• DPI_300
DOC_4X5 PDF
PNG
ZPL2 [2]
BASE64
BASE64
BASE64 [3]
DPI_203
DPI_203
• DPI_203 (default)
• DPI_300
DOC_4X6 PDF
PNG
ZPL2 [2]
BASE64
BASE64
BASE64 [3]
DPI_203
DPI_203
• DPI_203 (default)
• DPI_300
[2](1, 2, 3) If you have an older printer that does not support Unicode, please see this topic.
[3](1, 2, 3) If set the file format to ZPL2, the label is returned as raw ZPL.            

Sample Newgistics Label

Sample Newgistics Label