Create a PUDO Container Label and Shipping Label for Shipment to a PB Facility

HTTP Request

POST /v3/container-manifest

Summary

This operation prints a Pitney Bowes Returns Drop Off (PUDO) container label and UPS shipping label for shipping containerized PB Return parcels to a Pitney Bowes facility. Upon arrival at the facility, instructions on the container label prompt the facility to open and induct parcels to confirm receipt.

Note

This operation applies to PB PUDO containers. For CBDS containers, see Master Carton and Batch Labels. For PB Containers, see Standard Container.

Considerations

  1. The operation returns a container label (see the example below) and a Pitney Bowes Container ID.

  2. To specify a list of parcels, use the parcelTrackingNumbers array.

  3. The container’s parcels use the carrier listed in the API call’s carrier field. Currently, parcels must use PBCS.

  4. The PUDO container and UPS labels are returned as Base64-encoded ZPL2.

  5. If a shipper needs to make changes to a container label after printing it, the shipper can discard the original label, make the changes, and reissue the request.

Request URLs

Sandbox: https://shipping-api-sandbox.pitneybowes.com/shippingservices/v3/container-manifest
Production: https://shipping-api.pitneybowes.com/shippingservices/v3/container-manifest

Request Headers

Name

Description

Authorization

Required. OAuth token generated using the Generate an OAuth Token API.

Content-Type

Required. The media type of the request entity. Set this to application/json.

X-PB-TransactionId

Required. A unique identifier for the transaction, up to 25 characters. The following characters are allowed: letters, numbers, hyphens (-), and underscores (_).

Important: Ensure this is a unique ID.

Request Elements

Name

Data Type

Description

rates

Array[Rates Object]

Required. Specifies the carrier, service, and parcel type. The array takes one rates object. Set the following fields and value:

  • carrier: Set to PBCS.

  • serviceId: Set to RTN_FM.

  • specialServices: No Special Services apply.

containerType

String

The type of container used to transport the parcels. Possible values:

  • tote

  • carton

parcelTrackingNumbers

Array[String]

Lists all the parcels to be included in the container. The array identifies parcels by their tracking numbers.

weight

Object

Required. The parcel’s weight and unit of measure. A default of 400 OZ can be used for the tote.

weight.weight

BigDecimal

Required. The parcel’s weight.

weight.unitOfMeasurement

String

Required. The unit of measure. For USPS shipments, set this to OZ. Valid values, depending on the carrier:

  • OZ: Ounces

Dimensions

Dimension Object

Defines the parcel’s dimensions. For the order of dimensions, see the Dimension Object. Default dimensions of 18 x 18 x 18 inches can be used for the tote.

Dimension.unitOfMeasure

String

The parcel’s weight and unit of measure. A default unit of IN can be used for the tote.

Dimension.length

BigDecimal

Length of parcel or tote.

Dimension.width

BigDecimal

Width of parcel or tote.

Dimension.height

BigDecimal

Height of parcel or tote.

documents

Array[Object]

Required. Defines the container Container and Shipping Label.

documents.fileFormat

String

The file format for the printable label. Possible values:

  • ZPL2: Base64-encoded ZPL2. By default, the APIs print ZPL2 labels using the Unicode character set. If you have an older printer that does not support Unicode, see Dimension Object.

documents.size

String

The label size. Possible values:

  • DOC_4X6

documents.contentType

String

Determines the return type of the document. Set to BASE64.

documents.contents

String

Response only. Contains the text for the label.

firstMileShipmentDetails

String

Response only. Contains information for the shipment to the PB facility.

firstMileShipmentDetails.carrier

String

Response only.

firstMileShipmentDetails.shipmentId

String

Response only.

firstMileShipmentDetails.trackingNumber

String

Response only.

parameters

Array[Object]

Required. Defines reference fields and shipment options. Each object in the array specifies a different parameter and value. For available parameters, See Parameters.

parameters.name

String

The parameter.

parameters.value

String

The parameter’s value.

fromAddress

String

Response only. The from address.

toAddress

String

Response only. The to address.

Parameters

The parameters array in the Create a CONTAINER_LABEL request can take the parameters described here.

Name

Description

CLIENT_CONTAINER_ID

Required. The client’s ID for the container.

CARRIER_FACILITY_ID

Response only. The Pitney Bowes ID for the facility where the tote will be shipped.

For a list of facilities, see https://www.docs.pitneybowes.com/document/standard-delivery-product-service-guide#appendix-a.

SHIP_DATE

Required. The date the container CONTAINER_LABELs were created.

PRINT_CUSTOM_MESSAGE_1

Required. The handling instructions. This should be set to the value of PUDO Tote Open and Scan Packages /  Bolso : Abrir y escanear paquete

ORIGIN Facility ID

Required. The ID of the drop off location that the container is being shipped from.

CONTAINER_TRACKING_NUMBER

Response only Tracking number from the shipment label.

Sample Request for PUDO Container and Shipments Labels

Sample Request for PUDO Container and Shipments Labels
curl -X POST ".../v3/container-manifest" \
-H "Authorization: Bearer <oauth_token>" \
-H "Content-Type: application/json" \
-H "X-PB-TransactionId: ae49775701" \
-H "Cookie: JSESSIONID=BD41EF7159DC4854D58BE181424AC2B3; JSESSIONID=090EAF0D88F0F82299F8F93E065DAE4D"\
-d '
{
      "rates": [
      {
         "carrier": "pbcs",
         "serviceId": "RTN_FM"
       }
       ],
          "containerType": "Carton",
          "parcelTrackingNumbers": [
              "4204514092748000000000000000010000",
              "4204514092612000000000000000002000",
              "4204514092612000000000000000300000",
              "4204514092748000000000000000000400",
              "4204514092748000000000000000000400"
        ],
          "weight": {
              "unitOfMeasurement": "OZ",
              "weight": 40
         },
           "dimension": {
              "unitOfMeasurement": "IN",
              "length": "18",
              "width": "18",
              "height": "18"
         },
           "documents": [
         {
              "type": "SHIPPING_LABEL",
              "size": "DOC_4X6",
              "contentType": "BASE64",
              "fileFormat": "ZPL2"
         },
        {
              "type": "CONTAINER_LABEL",
              "size": "DOC_4X6",
              "contentType": "BASE64",
              "fileFormat": "ZPL2"
          }
         ],
           "parameters": [
         {
              "name": "CLIENT_CONTAINER_ID",
              "value": "PUDO987612345"
         },
        {
              "name": "ORIGIN_FACILITY_ID",
              "value": "AA0010"
        },
        {
              "name": "PRINT_CUSTOM_MESSAGE_1",
              "value": "PUDO Tote: Open and Scan Packages / Bolso : Abrir y escanear paquete"
          }
         ]
      }'

Sample Reponse

Sample Response
{
      "rates": [
     {
           "carrier": "pbcs",
           "specialServices": [],
           "serviceId": "RTN_FM"
      }
     ],
      "fromAddress": {
          "company": "",
          "name": "PDQ Mail Plus",
          "phone": "9148331133",
          "residential": false,
          "addressLines": [
              "2005 Palmer Ave"
      ],
          "cityTown": "Larchmont",
          "stateProvince": "NY",
          "postalCode": "10538-2437",
          "countryCode": "US",
          "carrierRoute": "C004",
          "deliveryPoint": "99",
          "status": "VALIDATED_AND_NOT_CHANGED"
      },
      "toAddress": {
          "company": "Pitney Bowes",
          "name": "Pitney Bowes Facility - EWR2",
          "residential": false,
          "addressLines": [
          "117 Interstate Blvd"
       ],
          "cityTown": "Monroe Township",
          "stateProvince": "NJ",
          "postalCode": "08831-3038",
          "countryCode": "US",
          "carrierRoute": "R005",
          "deliveryPoint": "17",
          "status": "VALIDATED_AND_NOT_CHANGED"
       },
      "containerType": "carton",
      "parcelTrackingNumbers": [
           "4204514092748000000000000000010000",
          "4204514092612000000000000000002000",
          "4204514092612000000000000000300000",
          "4204514092748000000000000000000400",
          "4204514092748000000000000000000400"
        ],
      "weight": {
           "unitOfMeasurement": "OZ",
           "weight": 40
       },
      "dimension": {
          "length": 18,
          "width": 18,
          "height": 18,
          "unitOfMeasurement": "IN",
          "irregularParcelGirth": 0
       },
      "documents": [
      {
          "contentType": "BASE64",
          "fileFormat": "ZPL2",
          "pages": [
            {
                "contents": "Cl5YQQ0KXkxSTg0KXk1OWQ0KXk1GTixODQpeTEgxMCwxMg0KXk1DWQ0KXlBPSQ0KXlBXODEyDQpeQ0kyNw0KXkZPMjg0LDUyNF5CWTNeQkNOLDEwNyxOLE4sTixBXkZWNDIwMDg4MzFeRlMNCl5GTzY2LDc5Ml5CWTNeQkNOLDIwOCxOLE4sTixBXkZWMVpGMTk5MEQwMzEzODgxNjk1XkZTDQpeRk8yMCw0MzFeQ1ZZXkJEMl5GSF9eRkQwMDM4NDAwODgzMTAwMDBbKT5fMUUwMV8xRDk2MVoxMzg4MTY5NV8xRFVQU05fMURGMTk5MERfMUUwN01JRURaRlZZN1VBRylDQyRNRC9PWFAmREQuLitEL1ZCRCVYRSU5WUw2MyJTXzBEXzFFXzA0XkZTDQpeRk8xNSw3XkEwTiwyMCwyNF5GVlBEUSBNQUlMIFBMVVNeRlMNCl5GTzE1LDI3XkEwTiwyMCwyNF5GVjkxNDgzMzExMzNeRlMNCl5GTzE1LDQ3XkEwTiwyMCwyNF5GVlBEUSBNQUlMIFBMVVNeRlMNCl5GTzE1LDY3XkEwTiwyMCwyNF5GVjIwMDUgUEFMTUVSIEFWRV5GUw0KXkZPMTUsODdeQTBOLDIwLDI0XkZWTEFSQ0hNT05UICBOWSAxMDUzOF5GUw0KXkZPMTUsMTQyXkEwTiwyOCwzMl5GVlNISVAgVE86IF5GUw0KXkZPNjEsMTY2XkEwTiwyOCwzMl5GVlBJVE5FWSBCT1dFUyBGQUNJTElUWSAtIEVXUjJeRlMNCl5GTzYxLDE5NF5BME4sMjgsMzJeRlZQSVRORVkgQk9XRVNeRlMNCl5GTzYxLDIyMl5BME4sMjgsMzJeRlYxMTcgSU5URVJTVEFURSBCTFZEXkZTDQpeRk82MSwyNTFeQTBOLDQ1LDQ0XkZWTU9OUk9FIFRPV05TSElQICBOSiAgMDg4MzFeRlMNCl5GTzQ0Niw5XkEwTiwzMCwzNF5GVjMgTEJTXkZTDQpeRk82ODMsOV5BME4sMjgsMzJeRlYxIE9GIDFeRlMNCl5GTzUwOCw1MV5BME4sMjIsMjZeRlZEV1Q6IDE4LDE4LDE4XkZTDQpeRk8yNjksNDM2XkEwTiw4MCw3MF5GVk5KIDA4OCA5LTAzXkZTDQpeRk8xMCwxMDMxXkEwTiwyMiwyNl5GVkJJTExJTkc6IFAvUF5GUw0KXkZPMTgwLDEyMDNeQTBOLDE0LDIwXkZWWE9MIDI0LjAxLjIzICAgICAgICAgIE5WNDUgNy4wQSAwMi8yMDI0Kl5GUw0KXkZPOSw2NzBeQTBOLDU2LDU4XkZWVVBTIEdST1VORF5GUw0KXkZPOSw3MzFeQTBOLDI2LDMwXkZWVFJBQ0tJTkcgIzogMVogRjE5IDkwRCAwMyAxMzg4IDE2OTVeRlMNCl5GTzY4OSw2NTBeR0IxMjQsMTI1LDEyNCxCLDBeRlMNCl5GTzAsNjQ4XkdCODExLDE0LDE0LEIsMF5GUw0KXkZPMCw0MjNeR0I4MTIsNCw0LEIsMF5GUw0KXkZPMjQ0LDQyM15HQjQsMjI1LDQsQiwwXkZTDQpeRk8wLDc3NF5HQjgxMiw1LDUsQiwwXkZTDQpeRk8wLDEwMTNeR0I4MTIsMTQsMTQsQiwwXkZTDQpeRk82MjksMTE0NwpeR0ZBLDAwOTY5LDAwOTY5LDAxOSxGRkZGRkZGRkZGRkZGRkZGRkZGRkZGRkZGRkZGRjAwMDAwMDAwMA0KRkZGRkZGRkZGRkZGRkZGRkZGRkZGRkZGRkZGRkYwMDAwMDAwMDANCkZGRkZGRkZGRkZGRkZGRkZGRkZGRkZGRkZGRkZGMDAwMDAwMDAwDQpGRkZGRkZGRkZGRkZGRkZGRkZGRkZGRkZGRkZGRjAwMDAwMDAwMA0KRjAwMDAwMDAwMDAwMDFGODAwMDAwMDAwMDAwMEYwMDAwMDAwMDANCkYwMDAwMDAwMDAwMDAxRjgwMDAwMDAwMDAwMDBGMDAwMDAwMDAwDQpGMDAwMDAwMDAwM0Y4MUY4M0ZDMDAwMDAwMDAwRjAwMDAwMDAwMA0KRjAwMDAwMDAwMDNGODFGODNGQzAwMDAwMDAwMEYwMDAwMDAwMDANCkYwMDAwMDAwMDBGRkY5RjlGRkYwMDAwMDAwMDBGMDAwMDAwMDAwDQpGMDAwMDAwMDAwRkZGOUY5RkZGMDAwMDAwMDAwRjAwMDAwMDAwMA0KRjAwMDAwMDAwMEZGRkZGRkZGRkMwMDAwMDAwMEYwMDAwMDAwMDANCkYwMDAwMDAwMDBGRkZGRkZGRkZDMDAwMDAwMDBGMDAwMDAwMDAwDQpGMDAwMDAwMDAwRjA3RkZGRjBGQzAwMDAwMDAwRjAwMDAwMDAwMA0KRjAwMDAwMDAwMEYwN0ZGRkYwRkMwMDAwMDAwMEYwMDAwMDAwMDANCkYwMDAwMDAwMDBGQzFGRkZDM0YwMDAwMDAwMDBGMDAwMDAwMDAwDQpGMDAwMDAwMDAwRkMxRkZGQzNGMDAwMDAwMDAwRjAwMDAwMDAwMA0KRjAwMDAwMDAwMEZGRkZGRkZGRjAwMDAwMDAwMEYwMDAwMDAwMDANCkYwMDAwMDAwMDBGRkZGRkZGRkYwMDAwMDAwMDBGMDAwMDAwMDAwDQpGMDAwMDAwMDAwM0ZGRkZGRkZDMDAwMDAwMDAwRjAwMDAwMDAwMA0KRjAwMDAwMDAwMDNGRkZGRkZGQzAwMDAwMDAwMEYwMDAwMDAwMDANCkZGRkZGRkZGRkZGRkZGRkZGRkZGRkZGRkZGRkZGMDAwMDAwMDAwDQpGRkZGRkZGRkZGRkZGRkZGRkZGRkZGRkZGRkZGRjAwMDAwMDAwMA0KRkZGRkZGRkZGRkZGRkZGRkZGRkZGRkZGRkZGRkYwMDAwMDAwMDANCkYwMDAwMDAwMDAwMUZGRkZGMDAwMDAwMDAwMDBGMDAwMDAwMDAwDQpGMDAwMDAwMDAwMDFGRkZGRjAwMDAwMDAwMDAwRjAwMDAwMDAwMA0KRjAwMDAwMDAwMDAzRkZGOUZDMDAwMDAwMDAwMEYwMDAwMDAwMDANCkYwMDAwMDAwMDAwM0ZGRjlGQzAwMDAwMDAwMDBGMDAwMDAwMDAwDQpGMDAwMDAwMDAwM0ZFMUY4N0ZDMDAwMDAwMDAwRjAwMDAwMDAwMA0KRjAwMDAwMDAwMDNGRTFGODdGQzAwMDAwMDAwMEYwMDAwMDAwMDANCkYwMDAwMDAwMDBGRjgxRjgzRkYwMDAwMDAwMDBGMDAwMDAwMDAwDQpGMDAwMDAwMDAwRkY4MUY4M0ZGMDAwMDAwMDAwRjAwMDAwMDAwMA0KRjAwMDAwMDAwMEZFMDFGODAzRjAwMDAwMDAwMEYwMDAwMDAwMDANCkYwMDAwMDAwMDBGRTAxRjgwM0YwMDAwMDAwMDBGMDAwMDAwMDAwDQpGMDAwMDAwMDAwRjAwMUY4MDBGMDAwMDAwMDAwRjAwMDAwMDAwMA0KRjAwMDAwMDAwMEYwMDFGODAwRjAwMDAwMDAwMEYwMDAwMDAwMDANCkYwMDAwMDAwMDAwMDAxRjgwMDAwMDAwMDAwMDBGMDAwMDAwMDAwDQpGMDAwMDAwMDAwMDAwMUY4MDAwMDAwMDAwMDAwRjBGRkRDMUMwMA0KRkZGRkZGRkZGRkZGRkZGRkZGRkZGRkZGRkZGRkYwRkZEQzFDMDANCkZGRkZGRkZGRkZGRkZGRkZGRkZGRkZGRkZGRkZGMDBDMUUzQzAwDQpGRkZGRkZGRkZGRkZGRkZGRkZGRkZGRkZGRkZGRjAwQzFFM0MwMA0KRkZGRkZGRkZGRkZGRkZGRkZGRkZGRkZGRkZGRkYwMEMxQTJDMDANCkZGRkZGRkZGRkZGRkZGRkZGRkZGRkZGRkZGRkZGMDBDMUI2QzAwDQpGRkZGRkZGRkZGRkZGRkZGRkZGRkZGRkZGRkZGRjAwQzFCNkMwMA0KMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMEMxQjZDMDANCjAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDBDMTlDQzAwDQowMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwQzE5Q0MwMA0KMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMEMxOUNDMDANCjAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDBDMTg4QzAwDQowMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMA0KMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDANCjAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwDQpeRE4NCl5YWg0K"
             }
         ],
          "size": "DOC_4X6",
          "type": "SHIPPING_LABEL"
          },
          {
          "contentType": "BASE64",
             "contents": "XlhBXkZPMTUsMjBeR0I3ODAsMTE4NSw1XkZTXkxSWV5GTzMwLDM1XkdCMzYwLDEyMCwxMjBeRlNeTFJZXkZPNzAsNjBeRkI1ODUsLCxMXkEwLDQyLDQ1XkZIXkZEUElUTkVZXzIwQk9XRVNeRlNeTFJZXkZPNTQwLDk1MF5HQjIzMCw4MCw4MF5GU15MUlleRk82NTAsMzVeRkI1ODUsLCxMXkEwLDMyLDMwXkZIXkZEMDIvMTQvMjAyNF5GU15MUlleRk8xNjAsMTEwXkZCMjAwLCwsTF5BMCwyOCwzNl5GSF5GRFJldHVybl5GU15GTzQwLDE4MF5GQjE3ODQsLCxMXkEwLDM1LDQwXkZIXkZEUFVET18yMC9fMjBQVURPXkZTXkZPNDAsMjYwXkZCNzg0LCwsTF5BMCwzNSw0MF5GSF5GRENsaWVudF8yMGNudHJfMjAjOl8yMFBVRE85ODc2MTIzNDVeRlNeTFJZXkZPNTgwLDE3NV5GQjU4NSwsLExeQTAsMzIsMzBeRkheRkRJTlNUUlVDVElPTlM6XkZTXkZPNTgwLDIwMl5GQjU4NSwsLExeQTAsNDIsNDVeRkheR0IxOTAsMSw0XkZTXkxSWV5GTzUwMCwyMTBeRkIyODAsNiwsUl5BMCwzMiwzMF5GSF5GRFBVRE9fMjBUb3RlOl8yME9wZW5fMjBhbmRfMjBTY2FuXzIwUGFja2FnZXNfMjAvXzIwQm9sc29fMjA6XzIwQWJyaXJfMjB5XzIwZXNjYW5lYXJfMjBwYXF1ZXRlXkZTXkZPMjMwLDQ2MF5CWE4sMTQsMjAwXkZIXkZEdDpjb250YWluZXJ8aTo2NWNkM2JhYjIwMWJlZWE2OWY0YTg2MzNeRlNeTFJZXkZPMTAwLDk3NV5GQjU4NSwsLExeQTAsMzYsMzReRkheRkQ2NWNkM2JhYjIwMWJlZWE2OWY0YTg2MzNeRlNeTFJZXkZPNTYwLDk3NV5GQjU4NSwsLExeQTAsMzUsMzVeRkheRkRFV1JfMjAtXzIwRVdSXkZTXkZXTl5YWg==",
          "fileFormat": "ZPL2",
          "size": "DOC_4X6",
          "type": "CONTAINER_LABEL"
         }
        ],
      "parameters": [
      {
          "name": "CLIENT_CONTAINER_ID",
          "value": "PUDO987612345"
      },
      {
          "name": "PRINT_CUSTOM_MESSAGE_1",
          "value": "PUDO Tote: Open and Scan Packages / Bolso : Abrir y escanear paquete"
      },
      {
          "name": "ORIGIN_FACILITY_ID",
          "value": "AA0010"
      },
     {
          "name": "SHIP_DATE",
          "value": "2024-02-14"
      },
      {
          "name": "CONTAINER_TRACKING_NUMBER",
          "value": "1ZF1990D0313881695"
      }
     ],
      "firstMileShipmentDetails": {
          "carrier": "UPS",
          "shipmentId": "UPS2215559652776084",
          "trackingNumber": "1ZF1990D0313881695"
      },
        "containerId": "65cd3bab201beea69f4a8633"
   }

Sample PUDO CONTAINER LABEL

Sample CONTAINER_LABELs

Error Codes

For a list of all error codes returned by the Ecommerce APIs, please see Error Codes.