Create a PB Presort Shipment

HTTP Request

POST /v1/shipments

Summary

This operation creates a post-paid label for a parcel that is part of a PB Presort pickup. Postage for a PB Presort label is not charged at the time of print.

Prerequisites

To use PB Presort, a merchant must be enrolled with a PB Presort facility and receive a Mailer ID, Job number, and other information required for shipping through PB Presort. To enroll a merchant, please see Onboard a Merchant to Print PB Presort Labels.

Considerations

1. For an overview of available services and operations when using PB Presort with the ECommerce APIs, see the PB Presort reference page.

2. This operation generates a post-paid label that incurs no charges until used.

3. PB Presort labels are supported for domestic shipments only. Note that domestic destinations include US territories/possessions, Freely Associated States, and APO/FPO/DPO. PB Presort does not require a customs form for these destinations.

4. Pitney Bowes verifies addresses for accuracy against current USPS data and makes corrections to delivery lines and last lines when possible. You can optionally limit the extent of corrections by enabling minimal address validation through the MINIMAL_ADDRESS_VALIDATION option in the shipmentOptions array. For a comparison of complete and minimal address validation, see this FAQ.

   IMPORTANT: If you enable minimal address validation, the shipper takes 100% responsibility for any undelivered packages due to violation of carrier-addressing guidelines and is responsible for any surcharge or adjustment fee levied by the carrier for such a violation.

5. Depending on the parcel type, you can print merchant-defined reference fields on shipping labels by setting the PRINT_CUSTOM_MESSAGE_1 and PRINT_CUSTOM_MESSAGE_2 options in the shipmentOptions array.

6. For the LGENV parcel type, the label will have an IMb.

7. For the PKG parcel type, the label will have an IMpb.

8. PB Presort does not support the following:

   • Rating is not supported for PB Presort shipments. Instead, use the rate charts provided by Pitney Bowes.

   • Refund requests are not supported for PB Presort labels. A Void Shipment request for a PB Presort label will fail.

   • The Transaction Reports API does not retrieve PB Presort labels.

   • FUTURE_SHIPMENT_DATE is not supported.

9. Tracking events show up only after PB Presort uploads the Shipping Services File to USPS. Tracking information can take a while to appear.

   You can use the Track a Package API to retrieve tracking events. You must set the carrier query parameter to USPS in the Tracking API request.

Request URLs

Sandbox: https://shipping-api-sandbox.pitneybowes.com/shippingservices/v1/shipments
Production: https://shipping-api.pitneybowes.com/shippingservices/v1/shipments

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.
X-PB-ShipmentGroupId	Required. The job number that represents the agreement between the merchant and PB Presort. This was provided by Pitney Bowes during merchant onboarding for PB Presort.
X-PB-Integrator-CarrierId	Required. The merchant’s Mailer ID (MID), as provided by Pitney Bowes during merchant onboarding for PB Presort.
X-PB-UnifiedErrorStructure	Recommended. Set this to true to use the standard error object if an error occurs.

Request / Response Elements

Required fields are marked Required. All other fields are optional, except fields marked RESPONSE ONLY, which appear only in the response.

Name	Data Type	Description
fromAddress	Address Object	Required. The origin address. If you want a different address to appear on the label from the one listed here, see this FAQ. The fromAddress object requires the following fields: addressLines postalCode countryCode
toAddress	Address Object	Required. The destination address. The following fields are required: addressLines postalCode countryCode
parcel	Parcel Object	Required. The parcel’s weight and dimensions. This object requires the following fields: weight dimension. For maximums and minimums, see PB Presort Services and Parcels. Important Entering incorrect dimensions might result in an undeliverable package or an additional postage fee.
rates	Array[Rates Object]	Required. Specifies the carrier, service, and parcel type. The response specifies the service charges. The array takes one rates object. The object requires the following fields and values: Field: Value: carrier PBPRESORT serviceId, parcelType See PB Presort Services and Parcels. specialServices See PB Presort Special Service.
documents	Array[Documents Object]	Required. Defines the label. The response returns the label as a URL or Base64 string. Set the following fields: Field: Value: type SHIPPING_LABEL size, fileFormat, contentType For valid combinations, see PB Presort Labels.
shipmentOptions	Array[Object]	Required. Each object in this array defines a shipment option. Each object takes the following two fields, which take string values: name: The shipment option. value: The option’s value. The following options are required: SHIPPER_ID: Set this to the merchant’s Shipper ID. For all available options, see Shipment Options. PERMIT_NUMBER: The merchant’s permit number for flats.
shipmentId	String	RESPONSE ONLY. The unique identifier for the shipment generated by the system.
parcelTrackingNumber	String	RESPONSE ONLY. The tracking number assigned to the shipment.

Sample Request

curl -X POST ".../v1/shipments" \
-H "Authorization: Bearer <oauth_token>" \
-H "Content-Type: application/json" \
-H "X-PB-TransactionId: 24c7d104-31de-4f6f-8bd0" \
-H "X-PB-ShipmentGroupId: 123456789" \
-H "X-PB-Integrator-CarrierId: 987654321" \
-H "X-PB-UnifiedErrorStructure: true" \
-d '
{
    "fromAddress": {
        "company": "Supplies",
        "name": "John Smith",
        "phone": "303-555-0000",
        "email": "john@example.com",
        "residential": false,
        "addressLines": [
            "4750 Walnut Street"
        ],
        "cityTown": "Boulder",
        "stateProvince": "CO",
        "postalCode": "80301",
        "countryCode": "US"
    },
    "toAddress": {
        "company": "Shop",
        "name": "Mary Jones",
        "phone": "620-555-0000",
        "email": "mary@example.com",
        "residential": false,
        "addressLines": [
            "4588 W Fulton"
        ],
        "cityTown": "Garden City",
        "stateProvince": "KS",
        "postalCode": "67846",
        "countryCode": "US"
    },
    "parcel": {
        "weight": {
            "unitOfMeasurement": "OZ",
            "weight": 3
        },
        "dimension": {
            "unitOfMeasurement": "IN",
            "length": 12,
            "width": 0.25,
            "height": 9
        }
    },
    "rates": [ {
        "carrier": "PBPRESORT",
        "serviceId": "BPM",
        "parcelType": "LGENV",
        "currencyCode": "USD"
    } ],
    "documents": [ {
        "size": "DOC_6X4",
        "printDialogOption": "NO_PRINT_DIALOG",
        "type": "SHIPPING_LABEL",
        "contentType": "URL",
        "fileFormat": "PDF"
    } ],
    "shipmentOptions": [ {
        "name": "SHIPPER_ID",
        "value": "9024324564"
    },{
        "name": "PERMIT_NUMBER",
        "value": "SHFL"
    },{
        "name": "MINIMAL_ADDRESS_VALIDATION",
        "value": "false"
    } ]
}'

Sample Response

{
    "fromAddress": {
        "company": "Supplies",
        "name": "John Smith",
        "phone": "303-555-0000",
        "email": "john@example.com",
        "residential": false,
        "addressLines": [
            "4750 Walnut St"
        ],
        "cityTown": "Boulder",
        "stateProvince": "CO",
        "postalCode": "80301-2532",
        "countryCode": "US",
        "carrierRoute": "C033",
        "deliveryPoint": "99"
    },
    "toAddress": {
        "company": "Shop",
        "name": "Mary Jones",
        "phone": "620-555-0000",
        "email": "mary@example.com",
        "residential": false,
        "addressLines": [
            "4588 W Fulton St"
        ],
        "cityTown": "Garden City",
        "stateProvince": "KS",
        "postalCode": "67846-9775",
        "countryCode": "US",
        "carrierRoute": "C007",
        "deliveryPoint": "84"
    },
    "parcel": {
        "weight": {
            "unitOfMeasurement": "OZ",
            "weight": 3.0
        },
        "dimension": {
            "length": 12.0,
            "width": 0.25,
            "height": 9.0,
            "unitOfMeasurement": "IN"
        }
    },
    "rates": [ {
        "carrier": "PBPRESORT",
        "parcelType": "LGENV",
        "inductionPostalCode": "80301",
        "specialServices": [],
        "serviceId": "BPM",
        "baseCharge": 0.0,
        "currencyCode": "USD",
        "destinationZone": "4",
        "totalCarrierCharge": 0.0
    } ],
    "documents": [ {
        "contentType": "URL",
        "contents": "https://.../6ad8a496574a4cc2ac66d9d9af31138e.pdf",
        "fileFormat": "PDF",
        "size": "DOC_6X4",
        "type": "SHIPPING_LABEL"
    } ],
    "shipmentOptions": [ {
        "name": "SHIPPER_ID",
        "value": "9024324564"
    },{
        "name": "PERMIT_NUMBER",
        "value": "SHFL"
    },{
        "name": "MINIMAL_ADDRESS_VALIDATION",
        "value": "false"
    } ],
    "parcelTrackingNumber": "0070698765432100221106510123814",
    "shipmentId": "PBPRESORT2200122647812392"
}

Sample PB Presort Label

The following is a sample label for a BPM Large Envelope.

Error Codes

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

 
 
 
 

• next
• previous |

© Copyright 2023 Pitney Bowes Inc. All rights reserved.