RocketShipIt

UPS Mail Innovations: Services, Tracking and API Setup

UPS Mail Innovations is UPS's high-volume, lightweight mailing product. UPS collects and line-hauls the mail and the USPS performs the final delivery, so a Mail Innovations parcel arrives in the recipient's mailbox rather than on the doorstep from a UPS driver. That handoff is what makes it cheap for lightweight, non-urgent parcels, and it is also the source of nearly every question about it: the shipment has two identities, one at UPS and one at USPS, and different parts of the API give you different ones.

Mail Innovations is available on the ups-rest and ups carriers. It is selected purely through the service and packaging_type params — there is no separate action.

Service codes#

Set service to one of these. Domestic services expect a matching packaging_type:

service Service Pair with packaging_type
M2 First Class Mail — domestic 59 (First Class)
M3 Priority Mail — domestic 60 (Priority)
M4 Expedited Mail Innovations — domestic any domestic packaging type
M5 Priority Mail Innovations — international —
M6 Economy Mail Innovations — international —

M4, Expedited Mail Innovations, is the workhorse and the one most integrations want: UPS ground network into the destination post office, USPS to the door.

Packaging types#

packaging_type Packaging Weight range
59 First Class —
60 Priority —
61 Machinables 6 – 15.99 oz
62 Irregulars 1 – 15.99 oz
63 Parcel Post 1 lb and over
64 BPM Parcel 1 – 15 lb
65 Media Mail 1 lb and over
66 BPM Flat under 1 lb
67 Standard Flat 1 – 15.99 oz

BPM is Bound Printed Matter. Media Mail and BPM carry USPS content restrictions — the contents genuinely have to qualify.

Creating a Mail Innovations label#

Alongside the usual shipment params, Mail Innovations requires usps_endorsement, cost_center and package_id:

{
  "carrier": "ups-rest",
  "action": "submitshipment",
  "params": {
    "key": "your-key-from-authenticate-request",
    "account_number": "YOUR_ACCOUNT_NUMBER",
    "service": "M4",
    "packaging_type": "62",
    "usps_endorsement": "1",
    "cost_center": "00000",
    "package_id": "1",
    "packages": [
      { "weight": 4, "length": 7 }
    ],
    "shipper": "RocketShipIt",
    "ship_addr1": "123 Main St",
    "ship_city": "Whitehall",
    "ship_state": "MT",
    "ship_code": "59759",
    "ship_country": "US",
    "ship_phone": "1231231234",
    "to_name": "John Doe",
    "to_addr1": "940 Presidio Ave",
    "to_addr2": "#103",
    "to_city": "San Francisco",
    "to_state": "CA",
    "to_code": "94115",
    "to_country": "US",
    "image_type": "GIF",
    "test": true
  }
}

cost_center is your own internal identifier for billing splits; UPS requires the field but does not care what is in it. package_id is a per-shipment sequence number.

USPS endorsements#

usps_endorsement tells USPS what to do with a piece it cannot deliver. It is required on domestic Mail Innovations:

usps_endorsement Endorsement
1 Return Service Requested
2 Forwarding Service Requested
3 Address Service Requested
4 Change Service Requested
5 No Service Selected

Signature and delivery confirmation#

For Mail Innovations forward shipments, USPS Delivery Confirmation is allowed on Priority, First Class, Machinables, Irregulars, Parcel Post, BPM Parcel and Media Mail packaging types.

It is prohibited on Standard Flats, BPM, BPM Flats and Parcels packaging types.

Tracking a Mail Innovations shipment#

Two things are different about Mail Innovations tracking, and between them they account for most of the "my tracking number does not work" reports.

1. On the legacy ups carrier you must set tracking_option to 03. RocketShipIt defaults tracking_option to 01, which is standard small-package tracking; 03 is what routes the inquiry to Mail Innovations. RocketShipIt also switches the UPS request option to 1 when you set 03, which is what that service requires.

{
  "carrier": "ups",
  "action": "track",
  "params": {
    "tracking_option": "03",
    "tracking_number": "9102084383041101186729",
    "test": true
  }
}

On ups-rest the tracking number goes straight to the REST tracking endpoint and tracking_option is not used, so a Mail Innovations number is tracked the same way as any other:

{
  "carrier": "ups-rest",
  "action": "track",
  "params": {
    "key": "your-key-from-authenticate-request",
    "tracking_number": "9102084383041101186729",
    "test": true
  }
}

2. There are two tracking numbers. UPS issues its own Mail Innovations tracking number, and USPS issues a Package Identification Code (PIC) — the 22-digit number that works on usps.com. When UPS returns a PIC on the label response RocketShipIt surfaces it on the package as an alternative tracking ID, so you can store the number your customers will recognise:

{
  "packages": [
    {
      "tracking_number": "MI000000000001",
      "alternative_tracking_ids": [
        { "type": "USPSPICNumber", "value": "9102084383041101186729" }
      ]
    }
  ]
}

Scan events during the UPS leg come from UPS; once the parcel is inducted into the postal network, movement shows up under the USPS PIC. Storing both numbers at label time is the only way to give a customer complete visibility later.

International Mail Innovations#

M5 (Priority Mail Innovations) and M6 (Economy Mail Innovations) carry international parcels. They need customs data like any other international shipment — a customs line list, customs_content_type, currency, and customs_forms to select the forms UPS generates (01,09 for a commercial invoice plus CN22). See ETD / Paperless Customs for how the forms work.

Examples#