Create Bulk Shipments ERR

ERR (Electronic Return Receipt) is an official United States Postal Service® (USPS) document designed to be equivalent to the hardcopy 'green card' Return Receipt.
It provides the following information:

  • Name of the Recipient
  • Time when article is delivered
  • Signature (image) of the Recipient
  • Address where the item is delivered, and
  • Date when the article gets delivered.

ERR is combined with certain classes and categories of mails, which are as follow:

  • First-Class Mail®
  • Priority Mail®

ERR Batch supports two types of Shipment Document format:

  • Shipping Label
  • Coversheet

This API "Create Bulk Shipments with ERR" operation requires the following information:

  • Recipient (Single or Multiple)
  • Carrier - USPS
  • Service
  • Parcel Type, and
  • Special Service.

The ERR API works at two levels: Shipment level and Root level. Root level is marked as Default, where multiple shipments are processed and entities are common for all shipments. While at Shipment level, entities might differ.
User can either define values for CarrierAccountID, ParcelType, ServiceID, and SpecialService respectively at the Root level for all shipments, or mention the values at Shipment level, i.e., for individual shipment(s).
If user does not provide values for the above-mentioned fields combinedly at Shipment level, then the default values for these fields provided at Root level will be considered. While, if user provides these values combinedly at Shipment Level for individual shipment(s), it will override the values defined at Root level.

Condition: The fields CarrierAccountID, ParcelType, ServiceID are treated as a combination, and values against each field must be provided if user selects Shipment level. In case any of these field(s) out of the mentioned combination is/are missing, it will return validation error.

SecuritybearerAuth
Request
header Parameters
X-PB-Developer-Partner-ID
string

The Developer-Partner-ID is assigned by PB to uniquely identify a developer's strategic business partners. If the developer is the sole business partner, this field is not required.

Request Body schema: application/json

This is the request body to create Bulk Shipment for ERR.

One of:

This ShipmentBatch contains the schema information for ERR Label.

name
required
string

Name of the of ERR Batch which consists of multiple shipments (shipments in bulk) for Label printing, e.g. ERR-Bulk05.

groupName
string

Indicates the name of the group of batches, which consists of multiple Batch groups.

size
required
string

This indicates the label size of the Bulk Shipment when it gets printed,i.e., DocSize. This has two options 8' X 11' or 4' X 6'.

Enum: "DOC_8X11" "DOC_4X6"
type
required
string

Indicates the type of the Batch Shipment, e.g., Shipping Label.

Value: "SHIPPING_LABEL"
format
string

Defines the type of the shipment which is printed, e.g., Shipping label gets printed in PDF form.

Value: "PDF"
carrierAccountId
required
string

A unique identifier associated with the Carrier account used by client users during shipment process. Default CarrierAccountID for this batch will be user's registered USPS account. User can override this value by defining it at Shipment level.

serviceId
required
string

A unique identifier given to the carrier-specific service. User can override this value by defining it at Shipment level.

parcelType
required
string

Parcel Type is required for creating a shipment while rating a parcel. And it varies as per USPS selected services, e.g. FRPKG, LGENV, TUBE, and PKG. User can override this value by defining it at Shipment level.

parcelID
string

A unique identifier given to the parcel or package corresponding to the selected service. This is optional field, but is used in few cases. Examples include BLM10, B1095, MT1098, etc. User can override this value by defining it at Shipment level.

Array of objects (SpecialServiceERR)
required
Array of objects (ShipmentERR)
Responses
200

The Bulk Shipment for ERR has been successfully created.

400

Invalid request.

401

The request could not be authorized.

500

The request could not be completed due to an internal server error.

post/api/v1/err/bulkShipments
Request samples
application/json
{
  • "name": "ERR-Bulk05",
  • "groupName": "string",
  • "size": "DOC_8X11",
  • "type": "SHIPPING_LABEL",
  • "format": "PDF",
  • "carrierAccountId": "qnpB1VkRMmw",
  • "serviceId": "PM",
  • "parcelType": "PKG",
  • "parcelID": "PMB4",
  • "specialServices": [
    ],
  • "shipments": [
    ]
}
Response samples
application/json
{
  • "batchId": "string",
  • "name": "string",
  • "groupName": "string",
  • "status": "SUBMITTED",
  • "addressValidation": {
    },
  • "rating": {
    },
  • "labelGeneration": {
    },
  • "labelDetails": {
    }
}