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 PB Shipping 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:

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:

The following options are required:

  • SHIPPER_ID: Set this to the merchant’s Shipper ID. For all available options, see Shipment Options.

    The following options are required for STANDARD LGENV, FCM LETTER and FLAT.

  • PERMIT_NUMBER: The merchant’s permit number for flats.

  • PERMIT_CITY: The city from which the merchant’s permit was issued.

  • PERMIT_STATE: The state from which the merchant’s permit was issued.

The following options are optional:

  • PERMIT_TYPE: Use of this name is only allowed for clients using a Non-Profit Permit, in which the PERMIT_NUMBER, PERMIT_CITY and PERMIT_STATE will need to reflect the actual values pertaining to that Non-Profit Permit.

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": "STANDARD",
        "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": "PERMIT_CITY",
        "value": "FOX VALLEY"
    },{
        "name": "PERMIT_STATE",
        "value": "IL"
    },{
        "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": "STANDARD",
        "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": "PERMIT_CITY",
        "value": "FOX VALLEY"
     },{
        "name": "PERMIT_STATE",
        "value": "IL"
     },{
        "name": "MINIMAL_ADDRESS_VALIDATION",
        "value": "false"
    } ],
    "parcelTrackingNumber": "0070698765432100221106510123814",
    "shipmentId": "PBPRESORT2200122647812392"
}

Sample PB Presort Label

The following is a sample label for a STANDARD LGENV.

Sample PB Presort Label

Error Codes

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