Create a Priority Mail Open and Distribute (PMOD) Label

HTTP Request

POST /v1/shipments

Summary

This operation purchases and prints a label for USPS®-approved Priority Mail Open and Distribute (PMOD) container.

PMOD uses Priority Mail to send containers containing lower classes of mail to USPS-authorized destination centers for processing, expediting the transport of the lower-class mailings. To use PMOD, shippers prepare their mailings and place them in approved USPS Priority Mail containers (sacks, trays, or tubs). They then affix PMOD labels to the containers and ship them to USPS-authorized centers, which open the containers and process the individual mailings according to their mail classes. The postage price is based on the weight of the contents (excluding the tare weight of the external container) and on regular Priority Mail distance-based prices.

For more information on PMOD, contact Client Support at ClientSupportTechServices@pb.com.

Considerations

  1. PMOD labels are supported for domestic shipments only.

  2. The maximum weight allowed for each container is 70 pounds.

  3. Stealth postage is not allowed with PMOD. You cannot hide postage. If you set the HIDE_TOTAL_CARRIER_CHARGE option to true, it will be ignored.

  4. The ADD_TO_MANIFEST shipment option is always considered true for PMOD labels. If you set the option to false, the API ignores the setting and still considers the option to be true.

  5. After you create the PMOD label, you must add the label to PS Form 3152. See Create a Manifest for PMOD Shipments.

Request URLs

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

Query Parameter

Name

Description

includeDeliveryCommitment

If set to true, returns estimated transit time. Transit time is returned as number of days.

Valid values:

  • true

  • false

See also:

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.

Accept-Language

Language and country code. Default: en-US

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-Shipper-Rate-Plan

Shipper rate plan, if applicable. For more information, see this FAQ.

X-PB-Integrator-CarrierId

Negotiated services rate, if applicable.

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. Set this to the merchant’s address. The following fields are required:

  • addressLines

  • postalCode

  • countryCode

toAddress

Address Object

Required. Set this to the destination facility. The shipper is responsible for providing the destination facility address information. The addressing data should be derived from the Drop Entry files located at the USPS FAST website: http://fast.usps.com.

If the DESTINATION_ENTRY_FACILITY PMOD option is set to DDU, include the entire destination address: name, addressLines, cityTown, stateProvince, postalCode, and countryCode.

If the option is set to NDC, ADC, ASF or SCF, the address need only include the cityTown, stateProvince, postalCode, and countryCode.

Note: In some cases the ZIP code on a PMOD label does not correspond to the city and state referenced. For example, the Washington DC Network Distribution Center (NDC) is addressed as NDC WASHINGTON DC 20799. The 20799 ZIP code, however, is the Maryland ZIP code where the NDC is located.

parcel

Parcel Object

Required. The parcel’s weight and dimensions.

rates

Array[Rates Object]

Required. Specifies the carrier and services. In a response, the array also specifies the service charges. The array takes only one object. The object requires the following fields and values:

  • carrier: Set to USPS

  • serviceId: Set to PMOD

  • parcelType: Set to one of the following PMOD parcel types:

    • EMMTB: Extended Managed Mail Tray Box

    • FTB: Full Tray Box

    • FTTB: Flat Tub Tray

    • HTB: Half Tray Box

    • SACK: Sack

  • specialServices: This array requires the following fields and values:

    • specialServiceId: Set to PMOD_OPTIONS

    • inputParameters: Add a separate object for each PMOD option listed in the PMOD Options table below.

documents

Array[Documents Object]

Required. Defines the label.

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 SHIPPER_ID shipment option is required. Set this to the merchant’s Shipper ID. For all available options, see Shipment Options.

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.

PMOD Options

The rates.specialServices.inputParameters array must contain a separate object for each of the following options. For an example, see the Sample Request after this table.

Name

Description

ORIGIN_ENTRY_FACILITY

Required. The type of facility where the shipment begins, i.e., the type of facility that will pick up the packages or receive your drop off of the packages. To determine which type of facility to use, visit the USPS FAST website at http://fast.usps.com.

Possible values:

  • ADC: Area Distribution Center

  • ASF: Auxiliary Service Center

  • DDU: Destination Delivery Unit

  • NDC: Network Distribution Center

  • SCF: Sectional Center Facility

Note: Do not use the facility for the fromAddress. Use the merchant’s address.

DESTINATION_ENTRY_FACILITY

Required. The type of facility the shipment is delivered to, i.e., where USPS opens the container and processes the individual mailings according to their mail classes. To determine which type of facility to use, visit the USPS FAST website at http://fast.usps.com.

Possible values:

  • ADC: Area Distribution Center

  • ASF: Auxiliary Service Center

  • DDU: Destination Delivery Unit

  • NDC: Network Distribution Center

  • SCF: Sectional Center Facility

Note: The destination facility’s address is entered in the toAddress field. For more information, see the Considerations section on this page.

ENCLOSED_MAIL_CLASS

Required. Possible values:

  • UGA: USPS Ground Advantage

  • LIB: Library Mail

  • MEDIA: Media Mail

  • MIX: Only very specific combinations are allowed. The shipper is responsible for following USPS rules. Pitney Bowes does not provide validation.

  • MKTMAIL: Marketing Mail

  • PER: Periodicals

  • PM: Priority Mail

ENCLOSED_PARCEL_TYPE

Required. Possible values:

  • LGENV: Large Envelope

  • LTR

  • MIX

  • PKG: Package

ENCLOSED_PAYMENT_METHOD

Required. If the enclosed parcels are evidenced and paid via USPS e-VS (Electronic Verification System), set this to ELECTRONIC. Otherwise set this to NONELECTRONIC.

DESTINATION_ENTRY_FACILITY_NAME

The facility name. Facility names can be found on fast.usps.com.

Required for all facilities except DDU facilities.

NASS_CODE

The NASS (National Air Surface System) code for the NDC, ADC, ASF, or SCF destination facility. The code consists of three to five alpha-numeric characters and can be found on fast.usps.com.

Required for all facilities except DDU facilities.

Sample Request

curl -X POST ".../v1/shipments" \
-H "Authorization: Bearer <oauth_token>" \
-H "Content-Type: application/json" \
-H "X-PB-TransactionId: <unique_transaction_id>" \
-H "X-PB-UnifiedErrorStructure: true" \
-d '
{
    "fromAddress": { ... },
    "toAddress": { ... },
    "parcel": {
        "weight": {
            "unitOfMeasurement": "OZ",
            "weight": "80"
        }
    },
    "rates": [ {
        "carrier": "USPS",
        "serviceId": "PMOD",
        "parcelType": "SACK",
        "specialServices": [ {
            "specialServiceId": "PMOD_OPTIONS",
            "inputParameters": [ {
                "name": "ORIGIN_ENTRY_FACILITY",
                "value": "DDU"
            },{
                "name": "DESTINATION_ENTRY_FACILITY",
                "value": "DDU"
            },{
                "name": "ENCLOSED_PARCEL_TYPE",
                "value": "PKG"
            },{
                "name": "ENCLOSED_MAIL_CLASS",
                "value": "STDPOST"
            },{
                "name": "ENCLOSED_PAYMENT_METHOD",
                "value": "NONELECTRONIC"
            } ]
        } ],
        "inductionPostalCode": "06484"
    } ],
    "documents": [ {
        "type": "SHIPPING_LABEL",
        "contentType": "URL",
        "size": "DOC_8X11",
        "fileFormat": "PDF",
        "printDialogOption": "NO_PRINT_DIALOG"
    } ],
    "shipmentOptions": [ {
        "name": "SHIPPER_ID",
        "value": "9024324564"
    },{
        "name": "ADD_TO_MANIFEST",
        "value": "true"
    },{
        "name": "MINIMAL_ADDRESS_VALIDATION",
        "value": "false"
    } ]
}'

Sample Response

{
    "fromAddress": { ... },
    "toAddress": { ... },
    "parcel": {
        "weight": {
            "unitOfMeasurement": "OZ",
            "weight": "80"
        }
    },
    "rates": [ {
        "carrier": "USPS",
        "parcelType": "SACK",
        "inductionPostalCode": "06484",
        "specialServices": [ {
            "specialServiceId": "PMOD_OPTIONS",
            "inputParameters": [ {
                "name": "ORIGIN_ENTRY_FACILITY",
                "value": "DDU"
            },{
                "name": "DESTINATION_ENTRY_FACILITY",
                "value": "DDU"
            },{
                "name": "ENCLOSED_PARCEL_TYPE",
                "value": "PKG"
            },{
                "name": "ENCLOSED_MAIL_CLASS",
                "value": "STDPOST"
            },{
                "name": "ENCLOSED_PAYMENT_METHOD",
                "value": "NONELECTRONIC"
            } ]
        } ],
        "dimensionalWeight": {
            "unitOfMeasurement": "OZ",
            "weight": 0
        },
        "deliveryCommitment": {
            "minEstimatedNumberOfDays": "1",
            "maxEstimatedNumberOfDays": "1",
            "estimatedDeliveryDateTime": "2021-04-24",
            "guarantee": "NONE",
            "additionalDetails": "By end of Day"
        },
        "serviceId": "PMOD",
        "totalCarrierCharge": 7.81,
        "baseCharge": 7.81,
        "currencyCode": "USD",
        "destinationZone": "1"
    } ],
    "documents": [ {
        "type": "SHIPPING_LABEL",
        "size": "DOC_8X11",
        "fileFormat": "PDF",
        "contentType": "URL",
        "contents": "https://.../usps/253536747/outbound/label/8cb101763888485296df9e08f58d25e3.pdf"
    } ],
    "shipmentOptions": [ {
        "name": "HIDE_TOTAL_CARRIER_CHARGE",
        "value": "false"
    },{
        "name": "SHIPPER_ID",
        "value": "9024324564"
    },{
        "name": "ADD_TO_MANIFEST",
        "value": "true"
    },{
        "name": "MINIMAL_ADDRESS_VALIDATION",
        "value": "false"
    },{
        "name": "SHIPPING_LABEL_RECEIPT",
        "value": "noOptions"
    } ],
    "shipmentId": "USPS2200253403883570",
    "parcelTrackingNumber": "9412309838644503839917"
}

Sample PMOD Label

Sample PMOD Label

Error Codes

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