Create ERR Single Coversheet

This API generates Electronic Return Receipt (ERR) artifacts for a parcel, including a coversheet, ERR barcode, and ERR stamp. The response output can be configured using the type parameter to return a coversheet, barcode and stamp images, or all outputs.

SecuritybearerAuth
Request
header Parameters
X-PB-LocationId
string

The X-PB-LocationId header identifies the enterprise, division, or partner location under which a shipment is processed and billed. If this header is not provided, the system automatically uses the enterprise-level location that was created during developer account onboarding. This default location is then used for shipment processing, carrier selection, and billing.

Location Scope

  • Carrier accounts and services available in a request must belong to the specified location or the default enterprise location.
  • Attempting to use carriers or services that are not configured for the resolved location will result in a validation error.

Requirement Rules

  • The X-PB-LocationId header is optional when the shipment origin country code matches the enterprise's default address country code.
  • The X-PB-LocationId header is required when the shipment origin country code differs from the enterprise's default address country code.
  • If the header is required but not provided, the API returns a validation error indicating that the location must be specified for the given shipment origin.
Request Body schema: application/json
format
string

The file format of the coversheet. For coversheet, supported format is PDF. For barcode and stamp, supported format is GIF

Enum: "PDF" "GIF"
size
string

The size of the coversheet. Default size is 10. This is applicable only for coversheet.

Enum: "10" "6X9.5" "6X9" "9.5x12"
type
required
string

The type of the output.

  • COVERSHEET: Returns coversheet output (backward compatible).
  • BARCODE.STAMP: Returns separate outputs for the ERR barcode and ERR stamp.
  • ALL: Returns three outputs:
    • coversheet (Content Type: URL, Format: PDF)
    • ERR barcode (Content Type: BASE64, Format: GIF)
    • ERR stamp (Content Type: URL, Format: GIF)
Enum: "COVERSHEET" "ALL" "BARCODE.STAMP"
carrierAccountId
required
string

A unique identifier assigned to the specific carrier account. Its value can be referred from the response of Get Carrier Accounts API.

parcelType
required
string

Type of the parcel, such as Letter or Envelope.

Enum: "LGENV" "PKG" "LTR"
serviceId
required
string

The unique identifier given to the carrier specific service, such as First Class Mail (FCM). It can be referred from response of Get Services API.

required
Array of objects

List of special services applied.

required
object
required
object
required
object
object
Array of objects

Additional metadata that needs to be stored for this shipment can be added here.
Supported values are Cost Account Name, Cost Account Id and Cost Account Code.
If Cost Account metadata is provided, all three Cost Account fields are required.

object

Contains additional reference fields that can be passed with an ERR request (single piece or batch). While USPS only accepts a single reference, these fields are used for internal tracking, exports, and reporting.

Responses
200

The ERR coversheet 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 error.

post/api/v1/err/coverSheet
Request samples
application/json
{
  • "format": "PDF",
  • "size": "6X9.5",
  • "type": "ALL",
  • "carrierAccountId": "JPZlE8DldKwx",
  • "parcelType": "LGENV",
  • "serviceId": "FCM",
  • "specialServices": [
    ],
  • "fromAddress": {
    },
  • "parcel": {
    },
  • "toAddress": {
    },
  • "shipmentOptions": {
    },
  • "metadata": [
    ],
  • "shippingReferences": {
    }
}
Response samples
application/json
{
  • "fromAddress": {
    },
  • "toAddress": {
    },
  • "labelLayout": [],
  • "parcel": {
    },
  • "shipmentOptions": {
    },
  • "shipmentId": "670d1820222f6a010ab3152c",
  • "parcelTrackingNumber": "9414809898643517885166",
  • "rate": {
    },
  • "correlationId": "65cc49aa8aeb46c1a77b1fc82a5ecba4"
}