USPS API Integration: Rates, Labels, Address Validation and SCAN Forms

RocketShipIt connects to the USPS APIs (the OAuth JSON APIs at apis.usps.com that replaced Web Tools) as the usps-rest carrier. You send one JSON request format, and RocketShipIt handles the OAuth token, the payment authorization header and USPS's multipart label responses.

With usps-rest you can:

Action What it does USPS API
authenticate Exchange your client id and secret for an access token OAuth 2.0
purchasepostage Get the payment token that labels are charged to Payments
getallrates Domestic, international and letter rates Domestic / International Prices
submitshipment Domestic shipping labels and return labels Labels
voidshipment Cancel (refund) an unused label Labels
createmanifest A SCAN form (PS Form 5630) for the day's labels SCAN Forms
addressvalidate Standardize an address, or look up city and state from a ZIP Addresses
timeintransit Delivery estimates between two ZIP codes Service Standards
track Tracking events for a package Tracking

Pickups are not available through usps-rest; see Schedule a Pickup for the carriers that do support them. International labels and customs forms are not available through usps-rest yet either (international rates are).

Which USPS carrier to use#

Carrier USPS API Use it for
usps-rest The USPS APIs (apis.usps.com, OAuth) All new integrations
usps Web Tools XML (ShippingAPI.dll, USERID) Existing integrations only
usps-evs eVS on the Web Tools hosts Existing integrations only

USPS has retired the Web Tools APIs; see Carrier API REST Migration Deadlines for the dates. If you still send "carrier": "usps", the migration section below covers what changes.

If you would rather buy postage through a reseller account than through your own USPS EPS account, Stamps.com is also supported as a separate carrier.

Credentials#

You need three things from USPS:

  1. An app on the USPS developer portal (developers.usps.com). Its consumer key and secret are your client_id and client_secret.
  2. An Enterprise Payment System (EPS) account, which postage is charged to. Its number is account_number.
  3. Your CRID and MID (Customer Registration ID and Mailer ID) from the USPS Business Customer Gateway. Labels are issued against them.
Parameter Value
client_id The app's consumer key
client_secret The app's consumer secret
scope Optional, e.g. "prices labels tracking"
key An access token from authenticate (see below)
test true sends requests to the USPS test environment (apis-tem.usps.com) instead of apis.usps.com
endpoint Optional: overrides the base URL entirely

Get an access token, and reuse it#

If you send client_id and client_secret without a key, RocketShipIt fetches a new token before every request. That works, but it is slow, and USPS throttles clients that request too many tokens. In production, call authenticate once, keep the token until it expires, and send it as key:

{
  "carrier": "USPS-REST",
  "action": "authenticate",
  "params": {
    "client_id": "abc123",
    "client_secret": "def987",
    "test": true
  }
}

The response has access_token, token_type, scope, issued_at and expires_in. Pass access_token as key on every other request until expires_in runs out. REST Authentication covers the same pattern for every OAuth carrier.

Get a payment token (needed for labels)#

Labels, return labels and voids also need a payment token, which tells USPS which account to charge. Get one with purchasepostage:

{
  "carrier": "USPS-REST",
  "action": "purchasepostage",
  "params": {
    "key": "your-key-from-authenticate-request",
    "account_number": "1000005549",
    "crid": "94879959",
    "mid": "901097701",
    "manifest_id": "901097701",
    "test": true
  }
}

The response's payment_token goes into each submitshipment and voidshipment request. RocketShipIt uses the same CRID, MID and EPS account for the shipper, the label owner and the payer.

Rates#

{
  "carrier": "USPS-REST",
  "action": "getallrates",
  "params": {
    "test": true,
    "key": "your-key-from-authenticate-request",
    "price_type": "RETAIL",
    "packages": [
      {
        "weight": 6
      }
    ],
    "ship_code": "59759",
    "to_code": "90210"
  }
}

Without service, RocketShipIt asks USPS for every eligible mail class (USPS's total-rates search). With service, it rates that one mail class. Each rate in the response has:

Field Meaning
local_service_code The mail class, e.g. USPS_GROUND_ADVANTAGE
service_code The USPS SKU for that price
zone The USPS zone
billing_weight The weight USPS billed (dimensional weight where it applies)

Rate parameters that matter:

Parameter Default Notes
price_type RETAIL COMMERCIAL or CONTRACT for business pricing
account_type e.g. EPS, with account_number, to get your account's prices
service all mail classes A USPS mail class (see below)
rate_indicator SP Single piece. Use PA for Priority Mail Express single piece, FE/FS/FB for flat rate, CP for cubic
processing_category NON_MACHINABLE MACHINABLE or NONSTANDARD. USPS now treats NON_MACHINABLE as NONSTANDARD, so send MACHINABLE for ordinary small boxes
packaging_type letter switches to USPS letter rates
ship_date today YYYY-MM-DD

International rates: send a to_country other than US, with the destination postal code in to_code_extended if the country uses one. RocketShipIt then uses the USPS international prices API. Extra services go in addons as USPS's numeric extra service codes, and insured_value sets the item value.

Missing package dimensions default to 5 × 5 × 5 inches for domestic rates. USPS prices large and light parcels by dimensional weight, so send real dimensions if you have them.

Mail classes#

service is passed to USPS unchanged as the mail class:

service Mail class
USPS_GROUND_ADVANTAGE USPS Ground Advantage
PRIORITY_MAIL Priority Mail
PRIORITY_MAIL_EXPRESS Priority Mail Express
PARCEL_SELECT Parcel Select (the label default)
PARCEL_SELECT_LIGHTWEIGHT Parcel Select Lightweight
MEDIA_MAIL Media Mail
LIBRARY_MAIL Library Mail
BOUND_PRINTED_MATTER Bound Printed Matter
USPS_CONNECT_LOCAL USPS Connect Local

The full list, and how it maps from the old Web Tools codes such as PRIORITY and EXPRESS, is in Shipping Service Codes.

Shipping labels#

{
  "carrier": "USPS-REST",
  "action": "submitshipment",
  "params": {
    "key": "your-key-from-authenticate-request",
    "payment_token": "key-from-PurchasePostage-response",
    "packages": [
      {
        "weight": 4.3,
        "length": 7,
        "width": 7,
        "height": 8,
        "reference_value": "reference1",
        "reference_value2": "reference2"
      }
    ],
    "service": "USPS_GROUND_ADVANTAGE",
    "shipper": "RocketShipIt",
    "ship_contact": "John Doe",
    "ship_addr1": "123 Main St",
    "ship_city": "Whitehall",
    "ship_state": "MT",
    "ship_code": "59759",
    "to_name": "John Doe",
    "to_addr1": "940 Presidio Ave",
    "to_addr2": "#103",
    "to_city": "San Francisco",
    "to_state": "CA",
    "to_code": "94115",
    "image_type": "PDF",
    "label_stock_type": "4X6LABEL",
    "test": true
  }
}

The response has the tracking_number (also returned as shipment_id, which voidshipment takes), charges (postage plus any USPS fees) and the label in packages[0].label, with its MIME type in label_format. reference_value and reference_value2 print on the label as customer references.

usps-rest labels are domestic only.

Label format and size#

Parameter Default Values
image_type PDF PDF, PNG, TIFF, JPG, GIF, SVG, ZPL203DPI, ZPL300DPI
label_stock_type 4X5LABEL 4X6LABEL, 4X5LABEL, 4X4LABEL, 6X4LABEL, 2X7LABEL
receipt_option SAME_PAGE, SEPARATE_PAGE, NONE

Two things catch people out:

  • For ZPL, send ZPL203DPI or ZPL300DPI, not ZPL. The value is passed to USPS unchanged, and USPS only accepts the DPI-specific names. See Thermal Printing.
  • The default label size is 4×5. For standard 4×6 thermal stock, send "label_stock_type": "4X6LABEL".

Any image_type other than PDF also sets receipt_option to NONE.

Packages, weights and addresses#

  • Weight is in pounds, always; weight_unit is not used by usps-rest. For 8 oz, send 0.5.
  • Dimensions are in inches. length_unit: "CM" is converted for you.
  • One package per request. Only the first entry in packages is used for rates and labels; send a request per package.
  • Validate addresses first. RocketShipIt asks USPS to accept the addresses as given rather than reject them, so a bad address produces a label rather than an error. Use addressvalidate before shipping.
  • to_code can include the ZIP+4 (94115-1234), or send the +4 as to_code_extended.
  • hold_at_location: true holds the package at the destination post office.
  • A one-word to_name with no to_company is sent as the company name. Send both first and last name for a person.

Return labels#

Set return_code to PRINT_RETURN_LABEL and use a return mail class as service, such as USPS_GROUND_ADVANTAGE_RETURN_SERVICE or PRIORITY_MAIL_RETURN_SERVICE. A payment_token is still required. See Return Labels for every carrier's return options.

Void a label#

{
  "carrier": "USPS-REST",
  "action": "voidshipment",
  "params": {
    "key": "your-key-from-authenticate-request",
    "payment_token": "key-from-PurchasePostage-response",
    "shipment_id": "9205500000000000000000",
    "test": true
  }
}

SCAN forms#

A SCAN form (PS Form 5630) lets the carrier scan one barcode for the whole day's packages instead of each label. Create one with createmanifest and the tracking numbers to include:

{
  "carrier": "USPS-REST",
  "action": "createmanifest",
  "params": {
    "key": "your-key-from-authenticate-request",
    "shipment_ids": ["9205500000000000000000", "9205500000000000000001"],
    "shipper": "RocketShipIt",
    "ship_addr1": "123 Main St",
    "ship_city": "Whitehall",
    "ship_state": "MT",
    "ship_code": "59759",
    "test": true
  }
}

ship_code is also the ZIP of the entry facility. ship_date defaults to tomorrow for SCAN forms. The form comes back as a PDF in documents, with the manifest number as its code. See End of Day for how manifests work across carriers.

Address validation#

addressvalidate standardizes a US address with the USPS Addresses API:

{
  "carrier": "USPS-REST",
  "action": "addressvalidate",
  "params": {
    "key": "your-key-from-authenticate-request",
    "to_addr1": "940 Presidio Ave",
    "to_addr2": "#103",
    "to_city": "San Francisco",
    "to_state": "CA",
    "to_code": "94115"
  }
}

The response includes the corrected address, whether it is residential, and USPS's delivery point checks (DPV confirmation, CMRA, vacant, business, central delivery point). Corrections come back as warnings. Send only to_code and you get the city and state for that ZIP instead. More in Address Validation.

Delivery estimates and tracking#

timeintransit needs only ship_code and to_code and returns USPS's delivery estimates; see Time in Transit.

track takes a tracking_number and returns USPS's tracking events; see Tracking for the request, the response and test numbers.

Errors#

USPS errors come back in data.errors, each with a code (USPS's error title and the parameter it refers to) and a description. Authentication failures appear there too. Errors from the international and letter price APIs are the exception: they are returned in meta.error_message. Carrier Errors covers the response format.

Moving from Web Tools to usps-rest#

Web Tools ("carrier": "usps") USPS APIs ("carrier": "usps-rest")
username (USERID), and password for tracking client_id + client_secret, or key
No test switch for most calls test: true uses apis-tem.usps.com
Labels without postage (or eVS for postage) Postage-paid labels charged to your EPS account via payment_token
PRIORITY, EXPRESS, MEDIA, … PRIORITY_MAIL, PRIORITY_MAIL_EXPRESS, MEDIA_MAIL, …
International labels and customs Not yet: international rates only

The rest of the request (ship_*, to_*, packages) stays the same, so most integrations change only the carrier, the credentials, the service codes and the label step (add purchasepostage and payment_token).